[PATCH] doc: kselftest: Fix KBUILD_OUTPUT usage instructions

[PATCH] doc: kselftest: Fix KBUILD_OUTPUT usage instructions

[Shuah Khan]

Fix KBUILD_OUTPUT usage instructions. The current documentation
is incorrect.

Signed-off-by: Shuah Khan <shuah@kernel.org>
---
 Documentation/dev-tools/kselftest.rst | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)

diff --git a/Documentation/dev-tools/kselftest.rst b/Documentation/dev-tools/kselftest.rst
index c8c03388b9de..6c910ddaa9f9 100644
--- a/Documentation/dev-tools/kselftest.rst
+++ b/Documentation/dev-tools/kselftest.rst
@@ -39,9 +39,9 @@ Build and run from user specific object directory (make O=dir)::
 
   $ make O=/tmp/kselftest kselftest
 
-Build and run KBUILD_OUTPUT directory (make KBUILD_OUTPUT=)::
+Build and run from KBUILD_OUTPUT directory (make KBUILD_OUTPUT=)::
 
-  $ make KBUILD_OUTPUT=/tmp/kselftest kselftest
+  $ export KBUILD_OUTPUT=/tmp/kselftest; make kselftest
 
 The above commands run the tests and print pass/fail summary to make it
 easier to understand the test results. Please find the detailed individual
@@ -65,9 +65,9 @@ Build and run from user specific object directory (make O=dir)::
 
   $ make O=/tmp/kselftest TARGETS="size timers" kselftest
 
-Build and run KBUILD_OUTPUT directory (make KBUILD_OUTPUT=)::
+Build and run from KBUILD_OUTPUT directory (make KBUILD_OUTPUT=)::
 
-  $ make KBUILD_OUTPUT=/tmp/kselftest TARGETS="size timers" kselftest
+  $ export KBUILD_OUTPUT=/tmp/kselftest; make TARGETS="size timers" kselftest
 
 The above commands run the tests and print pass/fail summary to make it
 easier to understand the test results. Please find the detailed individual
-- 
2.17.1

Re: [PATCH] doc: kselftest: Fix KBUILD_OUTPUT usage instructions

[Jonathan Corbet]

On Tue, 16 Apr 2019 08:26:51 -0600
Shuah Khan <shuah@kernel.org> wrote:

> Fix KBUILD_OUTPUT usage instructions. The current documentation
> is incorrect.
> 
> Signed-off-by: Shuah Khan <shuah@kernel.org>

So I'll confess to being a little confused by this one...

>  Documentation/dev-tools/kselftest.rst | 8 ++++----
>  1 file changed, 4 insertions(+), 4 deletions(-)
> 
> diff --git a/Documentation/dev-tools/kselftest.rst b/Documentation/dev-tools/kselftest.rst
> index c8c03388b9de..6c910ddaa9f9 100644
> --- a/Documentation/dev-tools/kselftest.rst
> +++ b/Documentation/dev-tools/kselftest.rst
> @@ -39,9 +39,9 @@ Build and run from user specific object directory (make O=dir)::
>  
>    $ make O=/tmp/kselftest kselftest
>  
> -Build and run KBUILD_OUTPUT directory (make KBUILD_OUTPUT=)::
> +Build and run from KBUILD_OUTPUT directory (make KBUILD_OUTPUT=)::
>  
> -  $ make KBUILD_OUTPUT=/tmp/kselftest kselftest
> +  $ export KBUILD_OUTPUT=/tmp/kselftest; make kselftest

Is there a particular reason why this variable needs to be set in the
environment rather than just in make?  More importantly, though, I don't
think this would work if you run it from the KBUILD_OUTPUT directory.  What
you're really doing is running with a separate output directory, right?

Thanks,

jon

Re: [PATCH] doc: kselftest: Fix KBUILD_OUTPUT usage instructions

[shuah]

On 4/16/19 9:26 AM, Jonathan Corbet wrote:
> On Tue, 16 Apr 2019 08:26:51 -0600
> Shuah Khan <shuah@kernel.org> wrote:
> 
>> Fix KBUILD_OUTPUT usage instructions. The current documentation
>> is incorrect.
>>
>> Signed-off-by: Shuah Khan <shuah@kernel.org>
> 
> So I'll confess to being a little confused by this one...

I generated the patch on a system with older .gitconfig. :)


> 
>>   Documentation/dev-tools/kselftest.rst | 8 ++++----
>>   1 file changed, 4 insertions(+), 4 deletions(-)
>>
>> diff --git a/Documentation/dev-tools/kselftest.rst b/Documentation/dev-tools/kselftest.rst
>> index c8c03388b9de..6c910ddaa9f9 100644
>> --- a/Documentation/dev-tools/kselftest.rst
>> +++ b/Documentation/dev-tools/kselftest.rst
>> @@ -39,9 +39,9 @@ Build and run from user specific object directory (make O=dir)::
>>   
>>     $ make O=/tmp/kselftest kselftest
>>   
>> -Build and run KBUILD_OUTPUT directory (make KBUILD_OUTPUT=)::
>> +Build and run from KBUILD_OUTPUT directory (make KBUILD_OUTPUT=)::
>>   
>> -  $ make KBUILD_OUTPUT=/tmp/kselftest kselftest
>> +  $ export KBUILD_OUTPUT=/tmp/kselftest; make kselftest
> 
> Is there a particular reason why this variable needs to be set in the
> environment rather than just in make?  More importantly, though, I don't
> think this would work if you run it from the KBUILD_OUTPUT directory.  What
> you're really doing is running with a separate output directory, right?
> 

That is correct. I am matching the instructions in the main Makefile:

# kbuild supports saving output files in a separate directory.
# To locate output files in a separate directory two syntaxes are supported.
# In both cases the working directory must be the root of the kernel src.
# 1) O=
# Use "make O=dir/to/store/output/files/"
#

# 2) Set KBUILD_OUTPUT
# Set the environment variable KBUILD_OUTPUT to point to the directory
# where the output files shall be placed.
# export KBUILD_OUTPUT=dir/to/store/output/files/
# make

kselftest documentation doesn't match the main Makefile. I am fixing
that with this patch.

For both cases the working directory is the src dir just like the main
Makefile.

I hope this helps.

thanks,
-- Shuah

Re: [PATCH] doc: kselftest: Fix KBUILD_OUTPUT usage instructions

[Jonathan Corbet]

On Tue, 16 Apr 2019 09:50:16 -0600
shuah <shuah@kernel.org> wrote:

> >> +Build and run from KBUILD_OUTPUT directory (make KBUILD_OUTPUT=)::
> >>   
> >> -  $ make KBUILD_OUTPUT=/tmp/kselftest kselftest
> >> +  $ export KBUILD_OUTPUT=/tmp/kselftest; make kselftest  
> > 
> > Is there a particular reason why this variable needs to be set in the
> > environment rather than just in make?  More importantly, though, I don't
> > think this would work if you run it from the KBUILD_OUTPUT directory.  What
> > you're really doing is running with a separate output directory, right?
> >   
> 
> That is correct. I am matching the instructions in the main Makefile:
> 
> # kbuild supports saving output files in a separate directory.

So my concern was right, then: this is not a way to "run from the
KBUILD_OUTPUT" directory; that seems certain to confuse people.  I'll
apply the patch so that the commands are right, but that could maybe use
some tweaking.

Thanks,

jon

Re: [PATCH] doc: kselftest: Fix KBUILD_OUTPUT usage instructions

[shuah]

On 4/16/19 1:59 PM, Jonathan Corbet wrote:
> On Tue, 16 Apr 2019 09:50:16 -0600
> shuah <shuah@kernel.org> wrote:
> 
>>>> +Build and run from KBUILD_OUTPUT directory (make KBUILD_OUTPUT=)::
>>>>    
>>>> -  $ make KBUILD_OUTPUT=/tmp/kselftest kselftest
>>>> +  $ export KBUILD_OUTPUT=/tmp/kselftest; make kselftest
>>>
>>> Is there a particular reason why this variable needs to be set in the
>>> environment rather than just in make?  More importantly, though, I don't
>>> think this would work if you run it from the KBUILD_OUTPUT directory.  What
>>> you're really doing is running with a separate output directory, right?
>>>    
>>
>> That is correct. I am matching the instructions in the main Makefile:
>>
>> # kbuild supports saving output files in a separate directory.
> 
> So my concern was right, then: this is not a way to "run from the
> KBUILD_OUTPUT" directory; that seems certain to confuse people.  I'll
> apply the patch so that the commands are right, but that could maybe use
> some tweaking.
> 

Yes. I can see it could confuse people.

I can tweak the wording to add that the working directory is the kernel
source dir, and that the command should be run from root of the kernel
source repo and send v2. The same changes probably need to be made for
the O= case if that isn't clear.

thanks,
-- Shuah