Skip to contentSkip to conversation

BR2_EXTERNAL, O: misc fixes and docs

PATCH New Yann E. MORIN 4 participants 11 messages Feb 21, 2014 – Feb 22, 2014 Kbuild

lore
Share & tools
lore
#0 lore raw

v3 cover BR2_EXTERNAL, O: misc fixes and docs

From: "Yann E. MORIN" <[email protected]>

Hello All!

Here is a small series that fixes use of relative paths in BR2_EXTERNAL and documents the limitations in the manual for BR2_EXTERNAL and O.

The first patch is an actual fix for this case:
make O=.. BR2_EXTERNAL=.. foo_defconfig

The rest are enhancements/clarifications to the manual.

As such, I propose them as candidates for 2014.02.

Changes v2 -> v3:
- refreshed on-top current master, should apply to -next as well.

Changes v1 -> v2:
- don't discourage relative paths, just properly document them (Thomas, Arnout)
- fix overriding BR2_EXTERNAL (J?r?my)
- simplify error message when BR2_EXTERNAL is not found (Arnout)
- document that $(O) is created

Regards,
Yann E. MORIN.

----------------------------------------------------------------
Yann E. MORIN (3):
Makefile: internally use absolute paths to BR2_EXTERNAL
manual: switch BR2_EXTERNAL examples to use absolute paths
manual: add explanations on limitations about using O=...

 Makefile                             |  5 +++++
 docs/manual/common-usage.txt         | 12 +++++++++---
 docs/manual/customize-outside-br.txt | 10 +++++-----
 3 files changed, 19 insertions(+), 8 deletions(-)
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.  |
'------------------------------^-------^------------------^--------------------'
#1 lore raw

PATCH v3 1/3 Makefile: internally use absolute paths to BR2_EXTERNAL

From: "Yann E. MORIN" <[email protected]>

Using a relative path for BR2_EXTERNAL, and using an external defconfig, such as in (from a Buildroot top-dir):
make O=.. BR2_EXTERNAL=.. foo_defconfig

is broken. It is unclear why the %_defconfig rule recurses in that case.

This patch internaly makes BR2_EXTERNAL canonical (ie. makes it an absolute path), and checks the directory exists.

Cc Peter Korsgaard <[email protected]>
Cc Romain Naour <[email protected]>
Cc Arnout Vandecappelle <[email protected]>

---
Changes v1->v2:
- fix override BR2_EXTERNAL (J?r?my)
- only one error message (Arnout)

---
 Makefile | 5 +++++
 1 file changed, 5 insertions(+)
Makefile +5 -0
index 98d32c0..4766160 100644
@@ -119,6 +119,11 @@ ifeq ($(BR2_EXTERNAL),)
   override BR2_EXTERNAL = support/dummy-external
   $(shell rm -f $(BR2_EXTERNAL_FILE))
 else
+  _BR2_EXTERNAL = $(shell cd $(BR2_EXTERNAL) >/dev/null 2>&1 && pwd)
+  ifeq ($(_BR2_EXTERNAL),)
+    $(error BR2_EXTERNAL='$(BR2_EXTERNAL)' does not exist, relatively to $(TOPDIR))
+  endif
+  override BR2_EXTERNAL := $(_BR2_EXTERNAL)
   $(shell echo BR2_EXTERNAL ?= $(BR2_EXTERNAL) > $(BR2_EXTERNAL_FILE))
 endif
 
Signature · 1 line
1.8.1.2
#2 lore raw

PATCH 1/3 Makefile: internally use absolute paths to BR2_EXTERNAL

"Yann E. MORIN" <[email protected]> schreef:

Quoted 33 lines

From: "Yann E. MORIN" <[email protected]>

Using a relative path for BR2_EXTERNAL, and using an external defconfig, such as in (from a Buildroot top-dir):
make O=.. BR2_EXTERNAL=.. foo_defconfig

is broken. It is unclear why the %_defconfig rule recurses in that case.

This patch internaly makes BR2_EXTERNAL canonical (ie. makes it an absolute path), and checks the directory exists.

Cc Peter Korsgaard <[email protected]>
Cc Romain Naour <[email protected]>
Cc Arnout Vandecappelle <[email protected]>

---
Changes v1->v2:
- fix override BR2_EXTERNAL (J?r?my)
- only one error message (Arnout)
---
Makefile | 5 +++++

1 file changed, 5 insertions(+)
Makefile +0 -0
index 98d32c0..4766160 100644
@@ -119,6 +119,11 @@ ifeq ($(BR2_EXTERNAL),)
  override BR2_EXTERNAL = support/dummy-external
  $(shell rm -f $(BR2_EXTERNAL_FILE))

else

Makefile ifeq ($(BR2_EXTERNAL),) · line 124

Quoted 3 lines
Makefile +3 -0
+  _BR2_EXTERNAL = $(shell cd $(BR2_EXTERNAL) >/dev/null 2>&1 && pwd)
+  ifeq ($(_BR2_EXTERNAL),)
+    $(error BR2_EXTERNAL='$(BR2_EXTERNAL)' does not exist, relatively to $(TOPDIR))

I think this should be 'relative to'.

Best regards,
Thomas

#3 lore raw

PATCH 1/3 Makefile: internally use absolute paths to BR2_EXTERNAL

Quoted 28 lines
Quoted 1 line
Quoted 1 line
Quoted 1 line
Quoted 1 line

"Thomas" == Thomas De Schampheleire <[email protected]> writes:

"Yann E. MORIN" <[email protected]> schreef:

Quoted 25 lines

From: "Yann E. MORIN" <[email protected]>

Using a relative path for BR2_EXTERNAL, and using an external defconfig, such as in (from a Buildroot top-dir):
make O=.. BR2_EXTERNAL=.. foo_defconfig

is broken. It is unclear why the %_defconfig rule recurses in that case.

This patch internaly makes BR2_EXTERNAL canonical (ie. makes it an absolute path), and checks the directory exists.

Cc Peter Korsgaard <[email protected]>
Cc Romain Naour <[email protected]>
Cc Arnout Vandecappelle <[email protected]>

---
Changes v1->v2:
- fix override BR2_EXTERNAL (J?r?my)
- only one error message (Arnout)
---
Makefile | 5 +++++

1 file changed, 5 insertions(+)
Quoted 13 lines

Makefile ifeq ($(BR2_EXTERNAL),) · line 124

Quoted 11 lines
Makefile +0 -0
index 98d32c0..4766160 100644
@@ -119,6 +119,11 @@ ifeq ($(BR2_EXTERNAL),)

override BR2_EXTERNAL = support/dummy-external
$(shell rm -f $(BR2_EXTERNAL_FILE))
else

Makefile +3 -0
+  _BR2_EXTERNAL = $(shell cd $(BR2_EXTERNAL) >/dev/null 2>&1 && pwd)
+  ifeq ($(_BR2_EXTERNAL),)
+    $(error BR2_EXTERNAL='$(BR2_EXTERNAL)' does not exist, relatively to $(TOPDIR))

I think this should be 'relative to'.

Committed with that changed, thanks.

Signature · 1 line
Bye, Peter Korsgaard
#4 lore raw

PATCH v3 2/3 manual: switch BR2_EXTERNAL examples to use absolute paths

In reply to Yann E. MORIN

From: "Yann E. MORIN" <[email protected]>

Although it is possible to use relative paths, there are a few pitfalls whith doing so.

To avoid confusion for a (newcoming) user, use absolute paths in the manual (as is done in examples for $(O)), since it is guaranteed to be working without corner cases.

---
Note: we only change our examples in the manual; using relative paths is still possible. There is no additional blurb in the manual that would favour using relative or absolute paths.

---
 docs/manual/customize-outside-br.txt | 10 +++++-----
 1 file changed, 5 insertions(+), 5 deletions(-)
docs/manual/customize-outside-br.txt +5 -5
index 585eedf..134ed64 100644
@@ -30,18 +30,18 @@ there is no need to pass +BR2_EXTERNAL+ at every +make+ invocation. It
 can however be changed at any time by passing a new value, and can be
 removed by passing an empty value.
 
-The +BR2_EXTERNAL+ path can be either an absolute or a relative path,
+*Note:* the +BR2_EXTERNAL+ path can be either an absolute or a relative path,
 but if it's passed as a relative path, it is important to note that it
-is interpreted relatively to the main Buildroot source directory, not
+is interpreted relatively to the main Buildroot source directory, *not*
 the Buildroot output directory.
 
 Some examples:
 
 -----
- buildroot/ $ make BR2_EXTERNAL=../foobar menuconfig
+ buildroot/ $ make BR2_EXTERNAL=/path/to/foobar menuconfig
 -----
 
-Starting from now on, external definitions from the +../foobar+
+Starting from now on, external definitions from the +/path/to/foobar+
 directory will be used:
 
 -----
@@ -52,7 +52,7 @@ directory will be used:
 We can switch to another external definitions directory at any time:
 
 -----
- buildroot/ $ make BR2_EXTERNAL=../barfoo xconfig
+ buildroot/ $ make BR2_EXTERNAL=/where/we/have/barfoo xconfig
 -----
 
 Or disable the usage of external definitions:
Signature · 1 line
1.8.1.2
#5 lore raw

PATCH 2/3 manual: switch BR2_EXTERNAL examples to use absolute paths

"Yann E. MORIN" <[email protected]> schreef:

Quoted 4 lines

From: "Yann E. MORIN" <[email protected]>

Although it is possible to use relative paths, there are a few pitfalls whith doing so.

With, but actually I think when would be better.

Quoted 27 lines

To avoid confusion for a (newcoming) user, use absolute paths in the manual (as is done in examples for $(O)), since it is guaranteed to be working without corner cases.

---
Note: we only change our examples in the manual; using relative paths is still possible. There is no additional blurb in the manual that would favour using relative or absolute paths.
---
docs/manual/customize-outside-br.txt | 10 +++++-----

1 file changed, 5 insertions(+), 5 deletions(-)
docs/manual/customize-outside-br.txt +0 -0
index 585eedf..134ed64 100644
@@ -30,18 +30,18 @@ there is no need to pass +BR2_EXTERNAL+ at every +make+ invocation. It

can however be changed at any time by passing a new value, and can be removed by passing an empty value.

docs/manual/customize-outside-br.txt +1 -1
-The +BR2_EXTERNAL+ path can be either an absolute or a relative path,
+*Note:* the +BR2_EXTERNAL+ path can be either an absolute or a relative path,

but if it's passed as a relative path, it is important to note that it

docs/manual/customize-outside-br.txt there is no need to pass +BR2_EXTERNAL+ at every +make+ invocation. It · line 35

Quoted 2 lines
docs/manual/customize-outside-br.txt +1 -1
-is interpreted relatively to the main Buildroot source directory, not
+is interpreted relatively to the main Buildroot source directory, *not*

I may be wrong, but I also think it should be 'relative' here...

Best regards,
Thomas

#6 lore raw

PATCH 2/3 manual: switch BR2_EXTERNAL examples to use absolute paths

Quoted 9 lines
Quoted 1 line
Quoted 1 line
Quoted 1 line
Quoted 1 line

"Thomas" == Thomas De Schampheleire <[email protected]> writes:

"Yann E. MORIN" <[email protected]> schreef:

Quoted 4 lines

From: "Yann E. MORIN" <[email protected]>

Although it is possible to use relative paths, there are a few pitfalls whith doing so.

With, but actually I think when would be better.

..

Quoted 7 lines

docs/manual/customize-outside-br.txt there is no need to pass +BR2_EXTERNAL+ at every +make+ invocation. It · line 35

Quoted 5 lines
docs/manual/customize-outside-br.txt +1 -1
-The +BR2_EXTERNAL+ path can be either an absolute or a relative path,
+*Note:* the +BR2_EXTERNAL+ path can be either an absolute or a relative path,

but if it's passed as a relative path, it is important to note that it

docs/manual/customize-outside-br.txt +1 -1
-is interpreted relatively to the main Buildroot source directory, not
+is interpreted relatively to the main Buildroot source directory, *not*

I may be wrong, but I also think it should be 'relative' here...

I think so too. Committed with that fixed, thanks both.

Signature · 1 line
Bye, Peter Korsgaard
#7 lore raw

PATCH v3 3/3 manual: add explanations on limitations about using O=...

In reply to Yann E. MORIN

From: "Yann E. MORIN" <[email protected]>

Using a relative path for O=... has limitations, since it is interpreted relative to the Buildroot tree, and thus may lead to unexpected results.

For example, running this:
make -C buildroot O=my-O

will not create my-O in the current working directory, but as a sub-directory of the Buildroot tree, here in buildroot/my-O

Explain this in the manual (as is similarly done for BR2_EXTERNAL). Also add a note that $(O) will be created if missing.

Also change O=.. and -C .. to O=<...> and -C <...> to make it explicit this is an ellipse, not a relative path.

---
 docs/manual/common-usage.txt | 12 +++++++++---
 1 file changed, 9 insertions(+), 3 deletions(-)
docs/manual/common-usage.txt +9 -3
index 127060d..9a8c92a 100644
@@ -40,7 +40,13 @@ Or:
  $ cd /tmp/build; make O=$PWD -C path/to/buildroot
 --------------------
 
-All the output files will be located under +/tmp/build+.
+All the output files will be located under +/tmp/build+. If the +O+
+path does not exist, Buildroot will create it.
+
+*Note:* the +O+ path can be either an absolute or a relative path, but if it's
+passed as a relative path, it is important to note that it is interpreted
+relative to the main Buildroot source directory, *not* the current working
+directory.
 
 When using out-of-tree builds, the Buildroot +.config+ and temporary
 files are also stored in the output directory. This means that you can
@@ -48,8 +54,8 @@ safely run multiple builds in parallel using the same source tree as
 long as they use unique output directories.
 
 For ease of use, Buildroot generates a Makefile wrapper in the output
-directory - so after the first run, you no longer need to pass +O=..+
-and +-C ..+, simply run (in the output directory):
+directory - so after the first run, you no longer need to pass +O=<...>+
+and +-C <...>+, simply run (in the output directory):
 
 --------------------
  $ make <target>
Signature · 1 line
1.8.1.2
#8 lore raw

PATCH 3/3 manual: add explanations on limitations about using O=...

"Yann E. MORIN" <[email protected]> schreef:

Quoted 48 lines

From: "Yann E. MORIN" <[email protected]>

Using a relative path for O=... has limitations, since it is interpreted relative to the Buildroot tree, and thus may lead to unexpected results.

For example, running this:
make -C buildroot O=my-O

will not create my-O in the current working directory, but as a sub-directory of the Buildroot tree, here in buildroot/my-O

Explain this in the manual (as is similarly done for BR2_EXTERNAL). Also add a note that $(O) will be created if missing.

Also change O=.. and -C .. to O=<...> and -C <...> to make it explicit this is an ellipse, not a relative path.

---
docs/manual/common-usage.txt | 12 +++++++++---

1 file changed, 9 insertions(+), 3 deletions(-)
docs/manual/common-usage.txt +7 -2
index 127060d..9a8c92a 100644
@@ -40,7 +40,13 @@ Or:
 $ cd /tmp/build; make O=$PWD -C path/to/buildroot
--------------------
 
-All the output files will be located under +/tmp/build+.
+All the output files will be located under +/tmp/build+. If the +O+
+path does not exist, Buildroot will create it.
+
+*Note:* the +O+ path can be either an absolute or a relative path, but if it's
+passed as a relative path, it is important to note that it is interpreted
+relative to the main Buildroot source directory, *not* the current working
+directory.
 

When using out-of-tree builds, the Buildroot +.config+ and temporary files are also stored in the output directory. This means that you can

docs/manual/common-usage.txt +0 -0
@@ -48,8 +54,8 @@ safely run multiple builds in parallel using the same source tree as

long as they use unique output directories.

For ease of use, Buildroot generates a Makefile wrapper in the output

docs/manual/common-usage.txt safely run multiple builds in parallel using the same source tree as · line 61

Quoted 7 lines
docs/manual/common-usage.txt +2 -3
-directory - so after the first run, you no longer need to pass +O=..+
-and +-C ..+, simply run (in the output directory):
+directory - so after the first run, you no longer need to pass +O=<...>+
+and +-C <...>+, simply run (in the output directory):
 
--------------------
 $ make <target>
#9 lore raw

PATCH 3/3 manual: add explanations on limitations about using O=...

Quoted 53 lines · Thomas De Schampheleire

"Yann E. MORIN" <[email protected]> schreef:

Quoted 52 lines

From: "Yann E. MORIN" <[email protected]>

Using a relative path for O=... has limitations, since it is interpreted relative to the Buildroot tree, and thus may lead to unexpected results.

For example, running this:
make -C buildroot O=my-O

will not create my-O in the current working directory, but as a sub-directory of the Buildroot tree, here in buildroot/my-O

Explain this in the manual (as is similarly done for BR2_EXTERNAL). Also add a note that $(O) will be created if missing.

Also change O=.. and -C .. to O=<...> and -C <...> to make it explicit this is an ellipse, not a relative path.

---
docs/manual/common-usage.txt | 12 +++++++++---

1 file changed, 9 insertions(+), 3 deletions(-)
docs/manual/common-usage.txt +7 -2
index 127060d..9a8c92a 100644
@@ -40,7 +40,13 @@ Or:
 $ cd /tmp/build; make O=$PWD -C path/to/buildroot
--------------------
 
-All the output files will be located under +/tmp/build+.
+All the output files will be located under +/tmp/build+. If the +O+
+path does not exist, Buildroot will create it.
+
+*Note:* the +O+ path can be either an absolute or a relative path, but if it's
+passed as a relative path, it is important to note that it is interpreted
+relative to the main Buildroot source directory, *not* the current working
+directory.
 

When using out-of-tree builds, the Buildroot +.config+ and temporary files are also stored in the output directory. This means that you can

docs/manual/common-usage.txt +0 -0
@@ -48,8 +54,8 @@ safely run multiple builds in parallel using the same source tree as

long as they use unique output directories.

For ease of use, Buildroot generates a Makefile wrapper in the output

docs/manual/common-usage.txt +2 -2
-directory - so after the first run, you no longer need to pass +O=..+
-and +-C ..+, simply run (in the output directory):
+directory - so after the first run, you no longer need to pass +O=<...>+
+and +-C <...>+, simply run (in the output directory):
Quoted 5 lines
Quoted 3 lines

--------------------

 $ make <target>
--
Signature · 1 line
Samuel
#10 lore raw

PATCH 3/3 manual: add explanations on limitations about using O=...

In reply to Yann E. MORIN
Quoted 15 lines
Quoted 1 line
Quoted 1 line
Quoted 1 line
Quoted 1 line

"Yann" == Yann E MORIN <[email protected]> writes:

From: "Yann E. MORIN" <[email protected]>
Using a relative path for O=... has limitations, since it is interpreted relative to the Buildroot tree, and thus may lead to unexpected results.

For example, running this:
make -C buildroot O=my-O

will not create my-O in the current working directory, but as a sub-directory of the Buildroot tree, here in buildroot/my-O

Explain this in the manual (as is similarly done for BR2_EXTERNAL). Also add a note that $(O) will be created if missing.

Quoted 6 lines

Also change O=.. and -C .. to O=<...> and -C <...> to make it explicit this is an ellipse, not a relative path.

Committed, thanks.

Signature · 1 line
Bye, Peter Korsgaard