Skip to contentSkip to conversation

Makefile: document make <package>-dirclean

PATCH New Vivien Didelot 5 participants 10 messages Jun 19, 2014 – Jun 20, 2014 Kbuild

lore
Share & tools
lore

Vivien Didelot

author
#0 lore raw

PATCH 1/1 Makefile: document make <package>-dirclean

Signed-off-by Vivien Didelot <[email protected]>
---
 Makefile | 1 +
 1 file changed, 1 insertion(+)
Makefile +1 -0
index a2681f6..81da5ae 100644
@@ -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:'
Signature · 1 line
2.0.0
#1 lore raw

PATCH 1/1 Makefile: document make <package>-dirclean

Vivien, All,

On 2014-06-19 13:44 -0400, Vivien Didelot spake thusly:

Quoted 10 lines
Signed-off-by Vivien Didelot <[email protected]>
---
 Makefile | 1 +
 1 file changed, 1 insertion(+)
Makefile +0 -0
index a2681f6..81da5ae 100644

Makefile help: · line 852

Quoted 4 lines
Makefile +1 -0
@@ -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.

Quoted 10 lines
Makefile +0 -0
 	@echo '  <package>-graph-depends    - generate graph of the dependency tree for package'
 	@echo
 	@echo 'Configuration:'
Signature · 6 lines
2.0.0

_______________________________________________
buildroot mailing list
buildroot at busybox.net
http://lists.busybox.net/mailman/listinfo/buildroot
Signature · 6 lines
.-----------------.--------------------.------------------.--------------------.
|  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.  |
'------------------------------^-------^------------------^--------------------'
author
#2 lore raw

PATCH 1/1 Makefile: document make <package>-dirclean

Hi Yann, All,

Quoted 17 lines
Quoted 6 lines
Makefile +1 -0
@@ -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

Quoted 7 lines

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.

Quoted 15 lines

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

#3 lore raw

PATCH 1/1 Makefile: document make <package>-dirclean

Vivien, All,

On 2014-06-19 14:48 -0400, Vivien Didelot spake thusly:

Quoted 6 lines
Quoted 6 lines
Quoted 6 lines
Makefile +1 -0
@@ -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--]

Quoted 8 lines
Quoted 3 lines

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.

Quoted 16 lines
Quoted 15 lines

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.
Quoted 2 lines

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.

Quoted 12 lines

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.
    [...]
Quoted 1 line

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.

Signature · 6 lines
.-----------------.--------------------.------------------.--------------------.
|  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.  |
'------------------------------^-------^------------------^--------------------'
#4 lore raw

PATCH 1/1 Makefile: document make <package>-dirclean

Dear Yann,

Quoted 2 lines · Yann E. MORIN

Vivien, All,

[...]

Quoted 3 lines

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:

Quoted 1 line

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

            ^^^^^^^^^^^^^^^^

;)

Signature · 1 line
Luca
#5 lore raw

PATCH 1/1 Makefile: document make <package>-dirclean

Luca, All,

On 2014-06-20 11:28 +0200, Luca Ceresoli spake thusly:

Quoted 7 lines

Dear Yann,

Quoted 2 lines · Yann E. MORIN

Vivien, All,

[...]

Quoted 1 line
Quoted 7 lines
Quoted 2 lines

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:

Quoted 1 line

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

           ^^^^^^^^^^^^^^^^

Hehe! :-)

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

Regards,
Yann E. MORIN.

Signature · 6 lines
.-----------------.--------------------.------------------.--------------------.
|  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.  |
'------------------------------^-------^------------------^--------------------'
#6 lore raw

PATCH 1/1 Makefile: document make <package>-dirclean

In reply to Yann E. MORIN

Hi,

Quoted 66 lines · Yann E. MORIN

Vivien, All,

On 2014-06-19 14:48 -0400, Vivien Didelot spake thusly:

Quoted 6 lines
Quoted 6 lines
Quoted 6 lines
Makefile +1 -0
@@ -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--]

Quoted 8 lines
Quoted 3 lines

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.

Quoted 16 lines
Quoted 15 lines

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.
Quoted 2 lines

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.

Quoted 12 lines

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.
    [...]
Quoted 1 line

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'.

Quoted 7 lines

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

#7 lore raw

PATCH 1/1 Makefile: document make <package>-dirclean

Dear Thomas De Schampheleire,

Quoted 2 lines · Thomas De Schampheleire

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

I agree.

Quoted 3 lines

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.

Quoted 4 lines

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.

Quoted 3 lines

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

Signature · 3 lines
Thomas Petazzoni, CTO, Free Electrons
Embedded Linux, Kernel and Android engineering
http://free-electrons.com
#8 lore raw

PATCH 1/1 Makefile: document make <package>-dirclean

Thomas?, Vivien, All,

On 2014-06-20 12:11 +0200, Thomas Petazzoni spake thusly:

Quoted 5 lines · Thomas De Schampheleire
Quoted 3 lines

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

Quoted 8 lines

I agree.

Quoted 3 lines

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! ;-)

Quoted 7 lines
Quoted 4 lines

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.

Quoted 7 lines
Quoted 3 lines

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.

Signature · 6 lines
.-----------------.--------------------.------------------.--------------------.
|  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.  |
'------------------------------^-------^------------------^--------------------'
#9 lore raw

PATCH 1/1 Makefile: document make <package>-dirclean

In reply to Yann E. MORIN

Dear Yann,

Quoted 35 lines · Yann E. MORIN

Vivien, All,

On 2014-06-19 13:44 -0400, Vivien Didelot spake thusly:

Quoted 10 lines
Signed-off-by Vivien Didelot <[email protected]>
---
  Makefile | 1 +
  1 file changed, 1 insertion(+)
Makefile +0 -0
index a2681f6..81da5ae 100644

Makefile help: · line 852

Quoted 4 lines
Makefile +1 -0
@@ -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:

Quoted 11 lines
     $ 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?

Signature · 1 line
Luca