[Buildroot] [PATCH] Makefile: document make <package>-dirclean

[Buildroot] [PATCH] Makefile: document make <package>-dirclean

[Vivien Didelot]

Signed-off-by: Vivien Didelot <vivien.didelot@savoirfairelinux.com>
---
 Makefile | 1 +
 1 file changed, 1 insertion(+)

diff --git a/Makefile b/Makefile
index a2681f6..81da5ae 100644
--- a/Makefile
+++ b/Makefile
@@ -849,6 +849,7 @@ help:
 	@echo '  toolchain              - build toolchain'
 	@echo '  <package>-rebuild      - force recompile <package>'
 	@echo '  <package>-reconfigure  - force reconfigure <package>'
+	@echo '  <package>-dirclean     - remove the whole <package> build directory'
 	@echo '  <package>-graph-depends    - generate graph of the dependency tree for package'
 	@echo
 	@echo 'Configuration:'
-- 
2.0.0

[Buildroot] [PATCH] Makefile: document make <package>-dirclean

[Yann E. MORIN]

Vivien, All,

On 2014-06-19 13:44 -0400, Vivien Didelot spake thusly:
> Signed-off-by: Vivien Didelot <vivien.didelot@savoirfairelinux.com>
> ---
>  Makefile | 1 +
>  1 file changed, 1 insertion(+)
> 
> diff --git a/Makefile b/Makefile
> index a2681f6..81da5ae 100644
> --- a/Makefile
> +++ b/Makefile
> @@ -849,6 +849,7 @@ help:
>  	@echo '  toolchain              - build toolchain'
>  	@echo '  <package>-rebuild      - force recompile <package>'
>  	@echo '  <package>-reconfigure  - force reconfigure <package>'
> +	@echo '  <package>-dirclean     - remove the whole <package> build directory'

I'm not specifically opposed to this, but then we are still missing
quite a few package-specific actions, of which the full list is
available in the manual:
    http://buildroot.net/downloads/manual/manual.html#pkg-build-steps

Also, it is explained in details in the manual how (and when) to rebuild
a package:
    http://buildroot.net/downloads/manual/manual.html#rebuild-pkg

Excerpt:
    You can ask buildroot to [remove the package directory] with the
    "make <package>-dirclean" command.

I believe we should only document the _very important_ commands in the
'make help' text, and direct the user to the manual for the others. E.g.
something like:

    $ make help
    [...]
    Build:
      all                    - make world
      toolchain              - build toolchain
      <package>-rebuild      - force recompile <package>
      <package>-reconfigure  - force reconfigure <package>
      <package>-graph-depends    - generate graph of the dependency tree for package
        See the manual [http://buildroot.net/downloads/manual/manual.html] for
        the complete list of per-package build actions.
    [...]

Regards,
Yann E. MORIN.

>  	@echo '  <package>-graph-depends    - generate graph of the dependency tree for package'
>  	@echo
>  	@echo 'Configuration:'
> -- 
> 2.0.0
> 
> _______________________________________________
> buildroot mailing list
> buildroot at busybox.net
> http://lists.busybox.net/mailman/listinfo/buildroot

-- 
.-----------------.--------------------.------------------.--------------------.
|  Yann E. MORIN  | Real-Time Embedded | /"\ ASCII RIBBON | Erics' conspiracy: |
| +33 662 376 056 | Software  Designer | \ / CAMPAIGN     |  ___               |
| +33 223 225 172 `------------.-------:  X  AGAINST      |  \e/  There is no  |
| http://ymorin.is-a-geek.org/ | _/*\_ | / \ HTML MAIL    |   v   conspiracy.  |
'------------------------------^-------^------------------^--------------------'

[Buildroot] [PATCH] Makefile: document make <package>-dirclean

[Vivien Didelot]

Hi Yann, All,

> > @@ -849,6 +849,7 @@ help:
> >  	@echo '  toolchain              - build toolchain'
> >  	@echo '  <package>-rebuild      - force recompile <package>'
> >  	@echo '  <package>-reconfigure  - force reconfigure <package>'
> > +	@echo '  <package>-dirclean     - remove the whole <package>
> > build directory'
> 
> I'm not specifically opposed to this, but then we are still missing
> quite a few package-specific actions, of which the full list is
> available in the manual:
>     http://buildroot.net/downloads/manual/manual.html#pkg-build-steps
> 
> Also, it is explained in details in the manual how (and when) to
> rebuild
> a package:
>     http://buildroot.net/downloads/manual/manual.html#rebuild-pkg
> 
> Excerpt:
>     You can ask buildroot to [remove the package directory] with the
>     "make <package>-dirclean" command.
> 
> I believe we should only document the _very important_ commands in
> the
> 'make help' text, and direct the user to the manual for the others.

Having only a portion of commands is confusing.

I would say, either put every package commands in `make help` or
no `make <package>-foo` commands at all.

> E.g.
> something like:
> 
>     $ make help
>     [...]
>     Build:
>       all                    - make world
>       toolchain              - build toolchain
>       <package>-rebuild      - force recompile <package>
>       <package>-reconfigure  - force reconfigure <package>
>       <package>-graph-depends    - generate graph of the dependency
>       tree for package
>         See the manual
>         [http://buildroot.net/downloads/manual/manual.html] for
>         the complete list of per-package build actions.

I'd remove the <package>-* command from `make help` and point to the
in-tree documentation instead (docs/manual/rebuilding-packages.txt).

That'd look like:

    $ make help
    [...]
    Build:
      all (or "world"?)      - make world
      toolchain              - build toolchain
      <package>              - compile only <package>
      <package>-<action>     - See the manual [docs/manual/rebuilding-packages.txt]
                               for the list of per-package build actions.
    [...]

What do you think?

Best,
Vivien

[Buildroot] [PATCH] Makefile: document make <package>-dirclean

[Yann E. MORIN]

Vivien, All,

On 2014-06-19 14:48 -0400, Vivien Didelot spake thusly:
> > > @@ -849,6 +849,7 @@ help:
> > >  	@echo '  toolchain              - build toolchain'
> > >  	@echo '  <package>-rebuild      - force recompile <package>'
> > >  	@echo '  <package>-reconfigure  - force reconfigure <package>'
> > > +	@echo '  <package>-dirclean     - remove the whole <package>
> > > build directory'
[--SNIP--]
> > I believe we should only document the _very important_ commands in
> > the
> > 'make help' text, and direct the user to the manual for the others.
> 
> Having only a portion of commands is confusing.
> 
> I would say, either put every package commands in `make help` or
> no `make <package>-foo` commands at all.

Well, I think we should still document a few important, usefull actions;
see below.

> > E.g.
> > something like:
> > 
> >     $ make help
> >     [...]
> >     Build:
> >       all                    - make world
> >       toolchain              - build toolchain
> >       <package>-rebuild      - force recompile <package>
> >       <package>-reconfigure  - force reconfigure <package>
> >       <package>-graph-depends    - generate graph of the dependency
> >       tree for package
> >         See the manual
> >         [http://buildroot.net/downloads/manual/manual.html] for
> >         the complete list of per-package build actions.
> 
> I'd remove the <package>-* command from `make help` and point to the
> in-tree documentation instead (docs/manual/rebuilding-packages.txt).

Note: everything in docs/manual/ is the source of the (on-line) manual.
Although readable as-is, it only gets really properly readable once
rendered into the manual.

So, I would not point to the content of docs/manual/ but to the on-line
manual, instead.

> That'd look like:
> 
>     $ make help
>     [...]
>     Build:
>       all (or "world"?)      - make world
>       toolchain              - build toolchain
>       <package>              - compile only <package>
>       <package>-<action>     - See the manual [docs/manual/rebuilding-packages.txt]
>                                for the list of per-package build actions.
>     [...]
> 
> What do you think?

'world' is an internal goal. The entry point is the 'all' gaol, and also the
default goal if no other is specified. I think we should not document
'world'.

Adding '<package>' is OK, but we should keep 'rebuild', 'reconfigure'
and 'graph-depends':
  - we want to prominently advertise the mere existence of 'graph-depends'
    to the unsuspecting user,
  - 'rebuild' and 'reconfigure' are important enough so we probably want
    to maintain them.

With those three acting as a template, and the pointer to the manual,
the user should (hopefully) easily:
  - find the other actions (from the manual)
  - remember how to toggle those actions (by memory and pattern matching
    with the actions visible in the 'make help' output)

But I usually suck at designing user-centric UI. One could say I'm a
weird, uncommon user with a tortured, twisted mind. ;-]

Regards,
Yann E. MORIN.

-- 
.-----------------.--------------------.------------------.--------------------.
|  Yann E. MORIN  | Real-Time Embedded | /"\ ASCII RIBBON | Erics' conspiracy: |
| +33 662 376 056 | Software  Designer | \ / CAMPAIGN     |  ___               |
| +33 223 225 172 `------------.-------:  X  AGAINST      |  \e/  There is no  |
| http://ymorin.is-a-geek.org/ | _/*\_ | / \ HTML MAIL    |   v   conspiracy.  |
'------------------------------^-------^------------------^--------------------'

[Buildroot] [PATCH] Makefile: document make <package>-dirclean

[Luca Ceresoli]

Dear Yann,

Yann E. MORIN wrote:
> Vivien, All,
>
> On 2014-06-19 13:44 -0400, Vivien Didelot spake thusly:
>> Signed-off-by: Vivien Didelot <vivien.didelot@savoirfairelinux.com>
>> ---
>>   Makefile | 1 +
>>   1 file changed, 1 insertion(+)
>>
>> diff --git a/Makefile b/Makefile
>> index a2681f6..81da5ae 100644
>> --- a/Makefile
>> +++ b/Makefile
>> @@ -849,6 +849,7 @@ help:
>>   	@echo '  toolchain              - build toolchain'
>>   	@echo '  <package>-rebuild      - force recompile <package>'
>>   	@echo '  <package>-reconfigure  - force reconfigure <package>'
>> +	@echo '  <package>-dirclean     - remove the whole <package> build directory'
>
> I'm not specifically opposed to this, but then we are still missing
> quite a few package-specific actions, of which the full list is
> available in the manual:
>      http://buildroot.net/downloads/manual/manual.html#pkg-build-steps
>
> Also, it is explained in details in the manual how (and when) to rebuild
> a package:
>      http://buildroot.net/downloads/manual/manual.html#rebuild-pkg
>
> Excerpt:
>      You can ask buildroot to [remove the package directory] with the
>      "make <package>-dirclean" command.
>
> I believe we should only document the _very important_ commands in the
> 'make help' text, and direct the user to the manual for the others. E.g.
> something like:
>
>      $ make help
>      [...]
>      Build:
>        all                    - make world
>        toolchain              - build toolchain
>        <package>-rebuild      - force recompile <package>
>        <package>-reconfigure  - force reconfigure <package>
>        <package>-graph-depends    - generate graph of the dependency tree for package
>          See the manual [http://buildroot.net/downloads/manual/manual.html] for
>          the complete list of per-package build actions.
>      [...]

I'm not entering the discussion about how many targets to put in make
help, but I agree that adding the manual URL here would be useful.

However I'd put http://buildroot.net/docs.html instead, because:
  - it's more concise;
  - it allows reading in other formats than HTML, and for nightlies too;
  - http://buildroot.net/downloads/manual/manual.html is long and ugly,
    and having the online HTML manual under "downloads" is kind of weird;
    I think we already discuss moving it to e.g. buildroot.net/manual
    or buildroot.net/docs or similar, so it may change in the future,
    while buildroot.net/docs.html is likely to stay for the forseeable
    future.

Maybe Samuel or ThomasDS were involved in that discussion?

-- 
Luca

[Buildroot] [PATCH] Makefile: document make <package>-dirclean

[Luca Ceresoli]

Dear Yann,

Yann E. MORIN wrote:
> Vivien, All,
>
[...]
>
> But I usually suck at designing user-centric UI. One could say I'm a
> weird, uncommon user with a tortured, twisted mind. ;-]

Come on Yann, you're able to say that more concisely:

 > | http://ymorin.is-a-geek.org/ | _/*\_ | / \ HTML MAIL    |
            ^^^^^^^^^^^^^^^^

;)

-- 
Luca

[Buildroot] [PATCH] Makefile: document make <package>-dirclean

[Thomas De Schampheleire]

Hi,

On Thu, Jun 19, 2014 at 10:10 PM, Yann E. MORIN <yann.morin.1998@free.fr> wrote:
> Vivien, All,
>
> On 2014-06-19 14:48 -0400, Vivien Didelot spake thusly:
>> > > @@ -849,6 +849,7 @@ help:
>> > >   @echo '  toolchain              - build toolchain'
>> > >   @echo '  <package>-rebuild      - force recompile <package>'
>> > >   @echo '  <package>-reconfigure  - force reconfigure <package>'
>> > > + @echo '  <package>-dirclean     - remove the whole <package>
>> > > build directory'
> [--SNIP--]
>> > I believe we should only document the _very important_ commands in
>> > the
>> > 'make help' text, and direct the user to the manual for the others.
>>
>> Having only a portion of commands is confusing.
>>
>> I would say, either put every package commands in `make help` or
>> no `make <package>-foo` commands at all.
>
> Well, I think we should still document a few important, usefull actions;
> see below.
>
>> > E.g.
>> > something like:
>> >
>> >     $ make help
>> >     [...]
>> >     Build:
>> >       all                    - make world
>> >       toolchain              - build toolchain
>> >       <package>-rebuild      - force recompile <package>
>> >       <package>-reconfigure  - force reconfigure <package>
>> >       <package>-graph-depends    - generate graph of the dependency
>> >       tree for package
>> >         See the manual
>> >         [http://buildroot.net/downloads/manual/manual.html] for
>> >         the complete list of per-package build actions.
>>
>> I'd remove the <package>-* command from `make help` and point to the
>> in-tree documentation instead (docs/manual/rebuilding-packages.txt).
>
> Note: everything in docs/manual/ is the source of the (on-line) manual.
> Although readable as-is, it only gets really properly readable once
> rendered into the manual.
>
> So, I would not point to the content of docs/manual/ but to the on-line
> manual, instead.
>
>> That'd look like:
>>
>>     $ make help
>>     [...]
>>     Build:
>>       all (or "world"?)      - make world
>>       toolchain              - build toolchain
>>       <package>              - compile only <package>
>>       <package>-<action>     - See the manual [docs/manual/rebuilding-packages.txt]
>>                                for the list of per-package build actions.
>>     [...]
>>
>> What do you think?
>
> 'world' is an internal goal. The entry point is the 'all' gaol, and also the
> default goal if no other is specified. I think we should not document
> 'world'.
>
> Adding '<package>' is OK, but we should keep 'rebuild', 'reconfigure'
> and 'graph-depends':
>   - we want to prominently advertise the mere existence of 'graph-depends'
>     to the unsuspecting user,
>   - 'rebuild' and 'reconfigure' are important enough so we probably want
>     to maintain them.
>

According to me, foo-dirclean is much more useful to the typical user
than foo-rebuild or foo-reconfigure. The latter two actions are
typically used for OVERRIDE_SRCDIR only, right? While -dirclean can be
used for any kind of (mis)action you performed.
So while I agree that some make targets should be listed to make sure
the unsuspecting user is aware that they exist, dirclean would
definitely be a part of this list, while rebuild/reconfigure need not
necessarily IMO.

Maybe we should create a list of all the possible targets (here in
this thread I mean) and then decide case-by-case if it's necessary to
list them in 'make help' or not?

Best regards,
Thomas

[Buildroot] [PATCH] Makefile: document make <package>-dirclean

[Thomas Petazzoni]

Dear Thomas De Schampheleire,

On Fri, 20 Jun 2014 11:40:10 +0200, Thomas De Schampheleire wrote:

> According to me, foo-dirclean is much more useful to the typical user
> than foo-rebuild or foo-reconfigure.

I agree.

> The latter two actions are
> typically used for OVERRIDE_SRCDIR only, right? While -dirclean can be
> used for any kind of (mis)action you performed.

Well, I also use -rebuild and -reconfigure when I directly hack into
output/build/<pkg>-<version>/ to do a quick test.

> So while I agree that some make targets should be listed to make sure
> the unsuspecting user is aware that they exist, dirclean would
> definitely be a part of this list, while rebuild/reconfigure need not
> necessarily IMO.

True.

> Maybe we should create a list of all the possible targets (here in
> this thread I mean) and then decide case-by-case if it's necessary to
> list them in 'make help' or not?

Another possible solution would be to have a <pkg>-help target that
lists all targets that are possible on a package, and then the main
"make help" only references that.

Best regards,

Thomas
-- 
Thomas Petazzoni, CTO, Free Electrons
Embedded Linux, Kernel and Android engineering
http://free-electrons.com

[Buildroot] [PATCH] Makefile: document make <package>-dirclean

[Yann E. MORIN]

Luca, All,

On 2014-06-20 11:28 +0200, Luca Ceresoli spake thusly:
> Dear Yann,
> 
> Yann E. MORIN wrote:
> >Vivien, All,
> >
> [...]
> >
> >But I usually suck at designing user-centric UI. One could say I'm a
> >weird, uncommon user with a tortured, twisted mind. ;-]
> 
> Come on Yann, you're able to say that more concisely:
> 
> > | http://ymorin.is-a-geek.org/ | _/*\_ | / \ HTML MAIL    |
>            ^^^^^^^^^^^^^^^^

Hehe! :-)

I'll look at your reviews on the legal stuff tonight.

Regards,
Yann E. MORIN.

-- 
.-----------------.--------------------.------------------.--------------------.
|  Yann E. MORIN  | Real-Time Embedded | /"\ ASCII RIBBON | Erics' conspiracy: |
| +33 662 376 056 | Software  Designer | \ / CAMPAIGN     |  ___               |
| +33 223 225 172 `------------.-------:  X  AGAINST      |  \e/  There is no  |
| http://ymorin.is-a-geek.org/ | _/*\_ | / \ HTML MAIL    |   v   conspiracy.  |
'------------------------------^-------^------------------^--------------------'

[Buildroot] [PATCH] Makefile: document make <package>-dirclean

[Yann E. MORIN]

Thomas?, Vivien, All,

On 2014-06-20 12:11 +0200, Thomas Petazzoni spake thusly:
> On Fri, 20 Jun 2014 11:40:10 +0200, Thomas De Schampheleire wrote:
> 
> > According to me, foo-dirclean is much more useful to the typical user
> > than foo-rebuild or foo-reconfigure.
> 
> I agree.
> 
> > The latter two actions are
> > typically used for OVERRIDE_SRCDIR only, right? While -dirclean can be
> > used for any kind of (mis)action you performed.
> 
> Well, I also use -rebuild and -reconfigure when I directly hack into
> output/build/<pkg>-<version>/ to do a quick test.

Well, I must really be a "different" kind of person, then, as I use
-reconfigure and -rebuild quite agressively (especially with
OVERRIDE_SRC_DIR), but just use plain: rm -rf b<TAB>pac<TAB> (which
expands in the shell to build/package-version/ ) to do the -dirclean
stuff; that's so much faster! ;-)

> > So while I agree that some make targets should be listed to make sure
> > the unsuspecting user is aware that they exist, dirclean would
> > definitely be a part of this list, while rebuild/reconfigure need not
> > necessarily IMO.
> 
> True.
> 
> > Maybe we should create a list of all the possible targets (here in
> > this thread I mean) and then decide case-by-case if it's necessary to
> > list them in 'make help' or not?
> 
> Another possible solution would be to have a <pkg>-help target that
> lists all targets that are possible on a package, and then the main
> "make help" only references that.

OK, I like that. :-)

Regards,
Yann E. MORIN.

-- 
.-----------------.--------------------.------------------.--------------------.
|  Yann E. MORIN  | Real-Time Embedded | /"\ ASCII RIBBON | Erics' conspiracy: |
| +33 662 376 056 | Software  Designer | \ / CAMPAIGN     |  ___               |
| +33 223 225 172 `------------.-------:  X  AGAINST      |  \e/  There is no  |
| http://ymorin.is-a-geek.org/ | _/*\_ | / \ HTML MAIL    |   v   conspiracy.  |
'------------------------------^-------^------------------^--------------------'