| Message ID | 20250317-cc-vars-v1-1-25edbadfd054@bootlin.com |
|---|---|
| State | Superseded |
| Headers | show |
| Series | Document missing toolchain related variables | expand |
On Mon Mar 17, 2025 at 5:03 PM CET, Antonin Godard via lists.yoctoproject.org wrote: > These toolchain variables are used in a native context. Some of the > BUILD_* variables missed documentation. Also, some of the base commands > were also not there so document them (FC and READELF). > > Some of existing BUILD_* variable documentation were missing the note > about their usage in a native context, so add it too so that all BUILD_* > variables are documented the same way. > > [YOCTO #15719] > > Signed-off-by: Antonin Godard <antonin.godard@bootlin.com> > --- > documentation/ref-manual/variables.rst | 107 +++++++++++++++++++++++++ > 1 file changed, 107 insertions(+) > > diff --git a/documentation/ref-manual/variables.rst b/documentation/ref-manual/variables.rst > index 861b04eaa..24b3f7db9 100644 > --- a/documentation/ref-manual/variables.rst > +++ b/documentation/ref-manual/variables.rst > @@ -985,6 +985,24 @@ system and gives an overview of their function and contents. > variable is a useful pointer in case a bug in the software being > built needs to be manually reported. > > + :term:`BUILD_AR` > + Specifies the architecture-specific archiver for the build host, > + derived in part from :term:`BUILD_PREFIX`:: > + > + BUILD_AR = "${BUILD_PREFIX}ar" > + > + When building in the ``-native`` context, :term:`AR` is set to the value > + of this variable by default. > + > + :term:`BUILD_AS` > + Specifies the architecture-specific assembler for the build host, > + derived in part from from :term:`BUILD_PREFIX`:: > + > + BUILD_AS = "${BUILD_PREFIX}ar" Should be "${BUILD_PREFIX}as", will fix in v2. Antonin
Hi Antonin, On 3/17/25 5:03 PM, Antonin Godard via lists.yoctoproject.org wrote: > These toolchain variables are used in a native context. Some of the > BUILD_* variables missed documentation. Also, some of the base commands > were also not there so document them (FC and READELF). > > Some of existing BUILD_* variable documentation were missing the note > about their usage in a native context, so add it too so that all BUILD_* > variables are documented the same way. > > [YOCTO #15719] > > Signed-off-by: Antonin Godard <antonin.godard@bootlin.com> > --- > documentation/ref-manual/variables.rst | 107 +++++++++++++++++++++++++ > 1 file changed, 107 insertions(+) > > diff --git a/documentation/ref-manual/variables.rst b/documentation/ref-manual/variables.rst > index 861b04eaa..24b3f7db9 100644 > --- a/documentation/ref-manual/variables.rst > +++ b/documentation/ref-manual/variables.rst > @@ -985,6 +985,24 @@ system and gives an overview of their function and contents. > variable is a useful pointer in case a bug in the software being > built needs to be manually reported. > > + :term:`BUILD_AR` > + Specifies the architecture-specific archiver for the build host, > + derived in part from :term:`BUILD_PREFIX`:: > + > + BUILD_AR = "${BUILD_PREFIX}ar" > + > + When building in the ``-native`` context, :term:`AR` is set to the value > + of this variable by default. > + It's not entirely clear to me from the text, but I believe we should only be consumer of this variable? Or the toolchain recipe/bbclass needs to set it accordingly, but otherwise nobody should *modify* it, right? I don't know what an archiver is, would there be a link we could provide to give hints to people maybe? Can suggest: """ When building a native recipe, :term:`AR` ... """ I would love to add a link to what a native recipe is but my grep-fu failed me today and couldn't find anything satisfying, do you have a suggestion maybe? A user question: Should we use BUILD_AR directly? or always AR? s/build host/:term:`Build Host`/ ? Same remarks for other BUILD_ addition in this patch. > + :term:`BUILD_AS` This is not alphabetically ordered though, since the next one is BUILD_ARCH, which should be before BUILD_AS. > + Specifies the architecture-specific assembler for the build host, > + derived in part from from :term:`BUILD_PREFIX`:: > + > + BUILD_AS = "${BUILD_PREFIX}ar" > + > + When building in the ``-native`` context, :term:`AS` is set to the value > + of this variable by default. > + > :term:`BUILD_ARCH` > Specifies the architecture of the build host (e.g. ``i686``). The > OpenEmbedded build system sets the value of :term:`BUILD_ARCH` from the > @@ -994,6 +1012,15 @@ system and gives an overview of their function and contents. > Specifies the architecture-specific assembler flags for the build > host. By default, the value of :term:`BUILD_AS_ARCH` is empty. > > + :term:`BUILD_CC` > + Specifies the architecture-specific C compiler for the build host, > + derived in part from :term:`BUILD_PREFIX` and :term:`BUILD_CC_ARCH`:: > + > + BUILD_CC = "${CCACHE}${BUILD_PREFIX}gcc ${BUILD_CC_ARCH}" > + This seems very gcc-specific but I cannot see the same thing for clang, so I guess it's fine? [...] > :term:`BUILD_STRIP` > Specifies the command to be used to strip debugging symbols from > binaries produced for the build host. By default, :term:`BUILD_STRIP` > points to > ``${``\ :term:`BUILD_PREFIX`\ ``}strip``. > thought: maybe have consistency with the way you expose the default value of the variable for the variables added in this patch? e.g. """ derived in part from :term:`BUILD_PREFIX`:: BUILD_STRIP = "${BUILD_PREFIX}strip" """ Cheers, Quentin
Hi Quentin, On Fri Mar 21, 2025 at 5:22 PM CET, Quentin Schulz wrote: > Hi Antonin, > > On 3/17/25 5:03 PM, Antonin Godard via lists.yoctoproject.org wrote: >> These toolchain variables are used in a native context. Some of the >> BUILD_* variables missed documentation. Also, some of the base commands >> were also not there so document them (FC and READELF). >> >> Some of existing BUILD_* variable documentation were missing the note >> about their usage in a native context, so add it too so that all BUILD_* >> variables are documented the same way. >> >> [YOCTO #15719] >> >> Signed-off-by: Antonin Godard <antonin.godard@bootlin.com> >> --- >> documentation/ref-manual/variables.rst | 107 +++++++++++++++++++++++++ >> 1 file changed, 107 insertions(+) >> >> diff --git a/documentation/ref-manual/variables.rst b/documentation/ref-manual/variables.rst >> index 861b04eaa..24b3f7db9 100644 >> --- a/documentation/ref-manual/variables.rst >> +++ b/documentation/ref-manual/variables.rst >> @@ -985,6 +985,24 @@ system and gives an overview of their function and contents. >> variable is a useful pointer in case a bug in the software being >> built needs to be manually reported. >> >> + :term:`BUILD_AR` >> + Specifies the architecture-specific archiver for the build host, >> + derived in part from :term:`BUILD_PREFIX`:: >> + >> + BUILD_AR = "${BUILD_PREFIX}ar" >> + >> + When building in the ``-native`` context, :term:`AR` is set to the value >> + of this variable by default. >> + > > It's not entirely clear to me from the text, but I believe we should > only be consumer of this variable? Or the toolchain recipe/bbclass needs > to set it accordingly, but otherwise nobody should *modify* it, right? Actually, users shouldn't even use this variable directly but only AR (see the explanation below). > I don't know what an archiver is, would there be a link we could provide > to give hints to people maybe? > > Can suggest: > > """ > When building a native recipe, :term:`AR` ... > """ > > I would love to add a link to what a native recipe is but my grep-fu > failed me today and couldn't find anything satisfying, do you have a > suggestion maybe? :ref:`ref-classes-native`? > > A user question: Should we use BUILD_AR directly? or always AR? Always AR, to my understanding. The native class takes care of setting AR to the value of BUILD_AR. In your recipe, you can use the AR variable to do your things, and its value will change on whether you're building the native recipe or not. You would only redefine BUILD_* variables if you were to add a new toolchain, basically. See toolchain/build-gcc.inc in OE-Core, for an example. > s/build host/:term:`Build Host`/ ? Yes, thanks. > Same remarks for other BUILD_ addition in this patch. > >> + :term:`BUILD_AS` > > This is not alphabetically ordered though, since the next one is > BUILD_ARCH, which should be before BUILD_AS. Well spotted, thank you! >> + Specifies the architecture-specific assembler for the build host, >> + derived in part from from :term:`BUILD_PREFIX`:: >> + >> + BUILD_AS = "${BUILD_PREFIX}ar" >> + >> + When building in the ``-native`` context, :term:`AS` is set to the value >> + of this variable by default. >> + >> :term:`BUILD_ARCH` >> Specifies the architecture of the build host (e.g. ``i686``). The >> OpenEmbedded build system sets the value of :term:`BUILD_ARCH` from the >> @@ -994,6 +1012,15 @@ system and gives an overview of their function and contents. >> Specifies the architecture-specific assembler flags for the build >> host. By default, the value of :term:`BUILD_AS_ARCH` is empty. >> >> + :term:`BUILD_CC` >> + Specifies the architecture-specific C compiler for the build host, >> + derived in part from :term:`BUILD_PREFIX` and :term:`BUILD_CC_ARCH`:: >> + >> + BUILD_CC = "${CCACHE}${BUILD_PREFIX}gcc ${BUILD_CC_ARCH}" >> + > > This seems very gcc-specific but I cannot see the same thing for clang, > so I guess it's fine? I will mention that this is the default value. Indeed if you were to use clang, the definition would be different from this one. I think there will be evolutions on that in the future, because the toolchain/ directory was made to prepare the ground for supporting clang (I think). > [...] > >> :term:`BUILD_STRIP` >> Specifies the command to be used to strip debugging symbols from >> binaries produced for the build host. By default, :term:`BUILD_STRIP` >> points to >> ``${``\ :term:`BUILD_PREFIX`\ ``}strip``. >> > > thought: maybe have consistency with the way you expose the default > value of the variable for the variables added in this patch? > > e.g. > > """ > derived in part from :term:`BUILD_PREFIX`:: > > BUILD_STRIP = "${BUILD_PREFIX}strip" > """ Yes, I was aiming at that, but missed this one - thanks! Antonin
Hi Antonin, On 3/26/25 10:17 AM, Antonin Godard wrote: > Hi Quentin, > > On Fri Mar 21, 2025 at 5:22 PM CET, Quentin Schulz wrote: >> Hi Antonin, >> >> On 3/17/25 5:03 PM, Antonin Godard via lists.yoctoproject.org wrote: >>> These toolchain variables are used in a native context. Some of the >>> BUILD_* variables missed documentation. Also, some of the base commands >>> were also not there so document them (FC and READELF). >>> >>> Some of existing BUILD_* variable documentation were missing the note >>> about their usage in a native context, so add it too so that all BUILD_* >>> variables are documented the same way. >>> >>> [YOCTO #15719] >>> >>> Signed-off-by: Antonin Godard <antonin.godard@bootlin.com> >>> --- >>> documentation/ref-manual/variables.rst | 107 +++++++++++++++++++++++++ >>> 1 file changed, 107 insertions(+) >>> >>> diff --git a/documentation/ref-manual/variables.rst b/documentation/ref-manual/variables.rst >>> index 861b04eaa..24b3f7db9 100644 >>> --- a/documentation/ref-manual/variables.rst >>> +++ b/documentation/ref-manual/variables.rst >>> @@ -985,6 +985,24 @@ system and gives an overview of their function and contents. >>> variable is a useful pointer in case a bug in the software being >>> built needs to be manually reported. >>> >>> + :term:`BUILD_AR` >>> + Specifies the architecture-specific archiver for the build host, >>> + derived in part from :term:`BUILD_PREFIX`:: >>> + >>> + BUILD_AR = "${BUILD_PREFIX}ar" >>> + >>> + When building in the ``-native`` context, :term:`AR` is set to the value >>> + of this variable by default. >>> + >> >> It's not entirely clear to me from the text, but I believe we should >> only be consumer of this variable? Or the toolchain recipe/bbclass needs >> to set it accordingly, but otherwise nobody should *modify* it, right? > > Actually, users shouldn't even use this variable directly but only AR (see > the explanation below). > Then we should make this very clear in the documentation for the variable. Essentially "treat this as a read-only variable except if you're adding support for a new toolchain" or something like this. >> I don't know what an archiver is, would there be a link we could provide >> to give hints to people maybe? >> >> Can suggest: >> >> """ >> When building a native recipe, :term:`AR` ... >> """ >> >> I would love to add a link to what a native recipe is but my grep-fu >> failed me today and couldn't find anything satisfying, do you have a >> suggestion maybe? > > :ref:`ref-classes-native`? > Works for me! >> >> A user question: Should we use BUILD_AR directly? or always AR? > > Always AR, to my understanding. The native class takes care of setting AR to the > value of BUILD_AR. In your recipe, you can use the AR variable to do your > things, and its value will change on whether you're building the native recipe > or not. > > You would only redefine BUILD_* variables if you were to add > a new toolchain, basically. See toolchain/build-gcc.inc in OE-Core, for an > example. > I think we should make this very clear. Essentially: """ This is only relevant when adding support for a new toolchain. Users are strongly encouraged to use :term:`AR` when wanting to use the archiver in recipes. """ or something along those lines? (same remark for all other BUILD_ variables). >>> + Specifies the architecture-specific assembler for the build host, >>> + derived in part from from :term:`BUILD_PREFIX`:: >>> + >>> + BUILD_AS = "${BUILD_PREFIX}ar" >>> + >>> + When building in the ``-native`` context, :term:`AS` is set to the value >>> + of this variable by default. >>> + >>> :term:`BUILD_ARCH` >>> Specifies the architecture of the build host (e.g. ``i686``). The >>> OpenEmbedded build system sets the value of :term:`BUILD_ARCH` from the >>> @@ -994,6 +1012,15 @@ system and gives an overview of their function and contents. >>> Specifies the architecture-specific assembler flags for the build >>> host. By default, the value of :term:`BUILD_AS_ARCH` is empty. >>> >>> + :term:`BUILD_CC` >>> + Specifies the architecture-specific C compiler for the build host, >>> + derived in part from :term:`BUILD_PREFIX` and :term:`BUILD_CC_ARCH`:: >>> + >>> + BUILD_CC = "${CCACHE}${BUILD_PREFIX}gcc ${BUILD_CC_ARCH}" >>> + >> >> This seems very gcc-specific but I cannot see the same thing for clang, >> so I guess it's fine? > > I will mention that this is the default value. Indeed if you were to use clang, > the definition would be different from this one. I think there will be > evolutions on that in the future, because the toolchain/ directory was made > to prepare the ground for supporting clang (I think). > This is actually not the default. It's set by the gcc toolchain, which I assume is the default (and only?) toolchain. I assume we want to state that you should not modify this variable, except if you are adding support for a new toolchain, but you can use it wherever the CC (for native recipes) or HOSTCC (for target recipes) variables are expected to be set? Cheers, Quentin
Hi Quentin, On Wed Mar 26, 2025 at 10:49 AM CET, Quentin Schulz wrote: > Hi Antonin, > > On 3/26/25 10:17 AM, Antonin Godard wrote: >> Hi Quentin, >> >> On Fri Mar 21, 2025 at 5:22 PM CET, Quentin Schulz wrote: >>> Hi Antonin, >>> >>> On 3/17/25 5:03 PM, Antonin Godard via lists.yoctoproject.org wrote: >>>> These toolchain variables are used in a native context. Some of the >>>> BUILD_* variables missed documentation. Also, some of the base commands >>>> were also not there so document them (FC and READELF). >>>> >>>> Some of existing BUILD_* variable documentation were missing the note >>>> about their usage in a native context, so add it too so that all BUILD_* >>>> variables are documented the same way. >>>> >>>> [YOCTO #15719] >>>> >>>> Signed-off-by: Antonin Godard <antonin.godard@bootlin.com> >>>> --- >>>> documentation/ref-manual/variables.rst | 107 +++++++++++++++++++++++++ >>>> 1 file changed, 107 insertions(+) >>>> >>>> diff --git a/documentation/ref-manual/variables.rst b/documentation/ref-manual/variables.rst >>>> index 861b04eaa..24b3f7db9 100644 >>>> --- a/documentation/ref-manual/variables.rst >>>> +++ b/documentation/ref-manual/variables.rst >>>> @@ -985,6 +985,24 @@ system and gives an overview of their function and contents. >>>> variable is a useful pointer in case a bug in the software being >>>> built needs to be manually reported. >>>> >>>> + :term:`BUILD_AR` >>>> + Specifies the architecture-specific archiver for the build host, >>>> + derived in part from :term:`BUILD_PREFIX`:: >>>> + >>>> + BUILD_AR = "${BUILD_PREFIX}ar" >>>> + >>>> + When building in the ``-native`` context, :term:`AR` is set to the value >>>> + of this variable by default. >>>> + >>> >>> It's not entirely clear to me from the text, but I believe we should >>> only be consumer of this variable? Or the toolchain recipe/bbclass needs >>> to set it accordingly, but otherwise nobody should *modify* it, right? >> >> Actually, users shouldn't even use this variable directly but only AR (see >> the explanation below). >> > > Then we should make this very clear in the documentation for the > variable. Essentially "treat this as a read-only variable except if > you're adding support for a new toolchain" or something like this. I've found the following wording: """ When building a :ref:`ref-classes-native` recipe, :term:`AR` is set to the value of this variable by default, so there is no need to use :term:`BUILD_AR` directly. """ "No need" is less strict than "never", because there might be some niche cases where you would use that. What do you think? Take meta/recipes-devtools/meson/meson_1.7.0.bb: it uses it in install_templates() which is called from do_install:append:class-nativesdk(), so here since we know we will always run in a native context, we can use BUILD_* variables. Although I would assume using regular AR, STRIP, etc. would work as well. [...] >>> >>> A user question: Should we use BUILD_AR directly? or always AR? >> >> Always AR, to my understanding. The native class takes care of setting AR to the >> value of BUILD_AR. In your recipe, you can use the AR variable to do your >> things, and its value will change on whether you're building the native recipe >> or not. >> >> You would only redefine BUILD_* variables if you were to add >> a new toolchain, basically. See toolchain/build-gcc.inc in OE-Core, for an >> example. >> > > I think we should make this very clear. Essentially: > > """ > This is only relevant when adding support for a new toolchain. Users are > strongly encouraged to use :term:`AR` when wanting to use the archiver > in recipes. > """ > > or something along those lines? See the wording I proposed above (which I will propagate to every BUILD_* definitions). > (same remark for all other BUILD_ variables). > >>>> + Specifies the architecture-specific assembler for the build host, >>>> + derived in part from from :term:`BUILD_PREFIX`:: >>>> + >>>> + BUILD_AS = "${BUILD_PREFIX}ar" >>>> + >>>> + When building in the ``-native`` context, :term:`AS` is set to the value >>>> + of this variable by default. >>>> + >>>> :term:`BUILD_ARCH` >>>> Specifies the architecture of the build host (e.g. ``i686``). The >>>> OpenEmbedded build system sets the value of :term:`BUILD_ARCH` from the >>>> @@ -994,6 +1012,15 @@ system and gives an overview of their function and contents. >>>> Specifies the architecture-specific assembler flags for the build >>>> host. By default, the value of :term:`BUILD_AS_ARCH` is empty. >>>> >>>> + :term:`BUILD_CC` >>>> + Specifies the architecture-specific C compiler for the build host, >>>> + derived in part from :term:`BUILD_PREFIX` and :term:`BUILD_CC_ARCH`:: >>>> + >>>> + BUILD_CC = "${CCACHE}${BUILD_PREFIX}gcc ${BUILD_CC_ARCH}" >>>> + >>> >>> This seems very gcc-specific but I cannot see the same thing for clang, >>> so I guess it's fine? >> >> I will mention that this is the default value. Indeed if you were to use clang, >> the definition would be different from this one. I think there will be >> evolutions on that in the future, because the toolchain/ directory was made >> to prepare the ground for supporting clang (I think). >> > > This is actually not the default. It's set by the gcc toolchain, which I > assume is the default (and only?) toolchain. For now, yes, I think it is the only one. So, saying that this value is the default is not wrong since bitbake.conf does: require toolchain/gcc.inc require toolchain/build-gcc.inc ? > I assume we want to state that you should not modify this variable, > except if you are adding support for a new toolchain, but you can use it > wherever the CC (for native recipes) or HOSTCC (for target recipes) > variables are expected to be set? I feel like there should even be a separate guide/section to explain how to add support for a new toolchain at some point? (how common of a task would that be, though?) I'm not sure we should in length on adding a new toolchain in the BUILD_* variable definitions. But let's see if we can agree on a wording that I'll propagate to every BUILD_* variable. :) Thanks, Antonin
Hi Antonin, On 3/26/25 11:33 AM, Antonin Godard wrote: > Hi Quentin, > > On Wed Mar 26, 2025 at 10:49 AM CET, Quentin Schulz wrote: >> Hi Antonin, >> >> On 3/26/25 10:17 AM, Antonin Godard wrote: >>> Hi Quentin, >>> >>> On Fri Mar 21, 2025 at 5:22 PM CET, Quentin Schulz wrote: >>>> Hi Antonin, >>>> >>>> On 3/17/25 5:03 PM, Antonin Godard via lists.yoctoproject.org wrote: >>>>> These toolchain variables are used in a native context. Some of the >>>>> BUILD_* variables missed documentation. Also, some of the base commands >>>>> were also not there so document them (FC and READELF). >>>>> >>>>> Some of existing BUILD_* variable documentation were missing the note >>>>> about their usage in a native context, so add it too so that all BUILD_* >>>>> variables are documented the same way. >>>>> >>>>> [YOCTO #15719] >>>>> >>>>> Signed-off-by: Antonin Godard <antonin.godard@bootlin.com> >>>>> --- >>>>> documentation/ref-manual/variables.rst | 107 +++++++++++++++++++++++++ >>>>> 1 file changed, 107 insertions(+) >>>>> >>>>> diff --git a/documentation/ref-manual/variables.rst b/documentation/ref-manual/variables.rst >>>>> index 861b04eaa..24b3f7db9 100644 >>>>> --- a/documentation/ref-manual/variables.rst >>>>> +++ b/documentation/ref-manual/variables.rst >>>>> @@ -985,6 +985,24 @@ system and gives an overview of their function and contents. >>>>> variable is a useful pointer in case a bug in the software being >>>>> built needs to be manually reported. >>>>> >>>>> + :term:`BUILD_AR` >>>>> + Specifies the architecture-specific archiver for the build host, >>>>> + derived in part from :term:`BUILD_PREFIX`:: >>>>> + >>>>> + BUILD_AR = "${BUILD_PREFIX}ar" >>>>> + >>>>> + When building in the ``-native`` context, :term:`AR` is set to the value >>>>> + of this variable by default. >>>>> + >>>> >>>> It's not entirely clear to me from the text, but I believe we should >>>> only be consumer of this variable? Or the toolchain recipe/bbclass needs >>>> to set it accordingly, but otherwise nobody should *modify* it, right? >>> >>> Actually, users shouldn't even use this variable directly but only AR (see >>> the explanation below). >>> >> >> Then we should make this very clear in the documentation for the >> variable. Essentially "treat this as a read-only variable except if >> you're adding support for a new toolchain" or something like this. > > I've found the following wording: > > """ > When building a :ref:`ref-classes-native` recipe, :term:`AR` is set to the > value of this variable by default, so there is no need to use > :term:`BUILD_AR` directly. > """ > > "No need" is less strict than "never", because there might be some niche cases > where you would use that. What do you think? > > Take meta/recipes-devtools/meson/meson_1.7.0.bb: it uses it in > install_templates() which is called from do_install:append:class-nativesdk(), so > here since we know we will always run in a native context, we can use BUILD_* > variables. Although I would assume using regular AR, STRIP, etc. would work as > well. > Seems like cargo and rust classes also need to specify BUILD_AR explicitly. So I rescind my comment on not using BUILD_AR directly, you just essentially don't need to set it and only need to use it in target recipes when wanting to point at the build host `ar`. Same for the other BUILD_* variables. > [...] >>>> >>>> A user question: Should we use BUILD_AR directly? or always AR? >>> >>> Always AR, to my understanding. The native class takes care of setting AR to the >>> value of BUILD_AR. In your recipe, you can use the AR variable to do your >>> things, and its value will change on whether you're building the native recipe >>> or not. >>> >>> You would only redefine BUILD_* variables if you were to add >>> a new toolchain, basically. See toolchain/build-gcc.inc in OE-Core, for an >>> example. >>> >> >> I think we should make this very clear. Essentially: >> >> """ >> This is only relevant when adding support for a new toolchain. Users are >> strongly encouraged to use :term:`AR` when wanting to use the archiver >> in recipes. >> """ >> >> or something along those lines? > > See the wording I proposed above (which I will propagate to every BUILD_* > definitions). > >> (same remark for all other BUILD_ variables). >> >>>>> + Specifies the architecture-specific assembler for the build host, >>>>> + derived in part from from :term:`BUILD_PREFIX`:: >>>>> + >>>>> + BUILD_AS = "${BUILD_PREFIX}ar" >>>>> + >>>>> + When building in the ``-native`` context, :term:`AS` is set to the value >>>>> + of this variable by default. >>>>> + >>>>> :term:`BUILD_ARCH` >>>>> Specifies the architecture of the build host (e.g. ``i686``). The >>>>> OpenEmbedded build system sets the value of :term:`BUILD_ARCH` from the >>>>> @@ -994,6 +1012,15 @@ system and gives an overview of their function and contents. >>>>> Specifies the architecture-specific assembler flags for the build >>>>> host. By default, the value of :term:`BUILD_AS_ARCH` is empty. >>>>> >>>>> + :term:`BUILD_CC` >>>>> + Specifies the architecture-specific C compiler for the build host, >>>>> + derived in part from :term:`BUILD_PREFIX` and :term:`BUILD_CC_ARCH`:: >>>>> + >>>>> + BUILD_CC = "${CCACHE}${BUILD_PREFIX}gcc ${BUILD_CC_ARCH}" >>>>> + >>>> >>>> This seems very gcc-specific but I cannot see the same thing for clang, >>>> so I guess it's fine? >>> >>> I will mention that this is the default value. Indeed if you were to use clang, >>> the definition would be different from this one. I think there will be >>> evolutions on that in the future, because the toolchain/ directory was made >>> to prepare the ground for supporting clang (I think). >>> >> >> This is actually not the default. It's set by the gcc toolchain, which I >> assume is the default (and only?) toolchain. > > For now, yes, I think it is the only one. > > So, saying that this value is the default is not wrong since bitbake.conf does: > > require toolchain/gcc.inc > require toolchain/build-gcc.inc > > ? > Well yeah ok, that's the default then :) Not entirely sure how meta/conf/toolchain/clang.inc should be used, but I guess it'll eventually come :) Fine with me, rescinding this comment as well. "default" term is fine. >> I assume we want to state that you should not modify this variable, >> except if you are adding support for a new toolchain, but you can use it >> wherever the CC (for native recipes) or HOSTCC (for target recipes) >> variables are expected to be set? > > I feel like there should even be a separate guide/section to explain how to add > support for a new toolchain at some point? (how common of a task would that be, > though?) > Considering we still don't have a second toolchain for the very popular clang, I'm not sure we'll have a third one soon :) But doesn't hurt to document the findings for when the second toolchain will be added, so that a third one would be easier to support. > I'm not sure we should in length on adding a new toolchain in the BUILD_* > variable definitions. > Fair. We can point at the terms from that yet-to-be-written "how to add a toolchain" section. Cheers, Quentin
diff --git a/documentation/ref-manual/variables.rst b/documentation/ref-manual/variables.rst index 861b04eaa..24b3f7db9 100644 --- a/documentation/ref-manual/variables.rst +++ b/documentation/ref-manual/variables.rst @@ -985,6 +985,24 @@ system and gives an overview of their function and contents. variable is a useful pointer in case a bug in the software being built needs to be manually reported. + :term:`BUILD_AR` + Specifies the architecture-specific archiver for the build host, + derived in part from :term:`BUILD_PREFIX`:: + + BUILD_AR = "${BUILD_PREFIX}ar" + + When building in the ``-native`` context, :term:`AR` is set to the value + of this variable by default. + + :term:`BUILD_AS` + Specifies the architecture-specific assembler for the build host, + derived in part from from :term:`BUILD_PREFIX`:: + + BUILD_AS = "${BUILD_PREFIX}ar" + + When building in the ``-native`` context, :term:`AS` is set to the value + of this variable by default. + :term:`BUILD_ARCH` Specifies the architecture of the build host (e.g. ``i686``). The OpenEmbedded build system sets the value of :term:`BUILD_ARCH` from the @@ -994,6 +1012,15 @@ system and gives an overview of their function and contents. Specifies the architecture-specific assembler flags for the build host. By default, the value of :term:`BUILD_AS_ARCH` is empty. + :term:`BUILD_CC` + Specifies the architecture-specific C compiler for the build host, + derived in part from :term:`BUILD_PREFIX` and :term:`BUILD_CC_ARCH`:: + + BUILD_CC = "${CCACHE}${BUILD_PREFIX}gcc ${BUILD_CC_ARCH}" + + When building in the ``-native`` context, :term:`CC` is set to the value + of this variable by default. + :term:`BUILD_CC_ARCH` Specifies the architecture-specific C compiler flags for the build host. By default, the value of :term:`BUILD_CC_ARCH` is empty. @@ -1011,12 +1038,31 @@ system and gives an overview of their function and contents. :term:`CFLAGS` is set to the value of this variable by default. + :term:`BUILD_CPP` + Specifies the C preprocessor command (to both the C and the C++ compilers) + when building for the build host, derived in part from + :term:`BUILD_PREFIX` and :term:`BUILD_CC_ARCH`:: + + BUILD_CPP = "${BUILD_PREFIX}gcc ${BUILD_CC_ARCH} -E" + + When building in the ``-native`` context, :term:`CPP` is set to the value + of this variable by default. + :term:`BUILD_CPPFLAGS` Specifies the flags to pass to the C preprocessor (i.e. to both the C and the C++ compilers) when building for the build host. When building in the ``-native`` context, :term:`CPPFLAGS` is set to the value of this variable by default. + :term:`BUILD_CXX` + Specifies the architecture-specific C++ compiler for the build host, + derived in part from :term:`BUILD_PREFIX` and :term:`BUILD_CC_ARCH`:: + + BUILD_CXX = "${CCACHE}${BUILD_PREFIX}g++ ${BUILD_CC_ARCH}" + + When building in the ``-native`` context, :term:`CXX` is set to the value + of this variable by default. + :term:`BUILD_CXXFLAGS` Specifies the flags to pass to the C++ compiler when building for the build host. When building in the ``-native`` context, @@ -1029,12 +1075,18 @@ system and gives an overview of their function and contents. value of :term:`BUILD_CC_ARCH`, assuming :term:`BUILD_CC_ARCH` is set. + When building in the ``-native`` context, :term:`FC` is set to the value + of this variable by default. + :term:`BUILD_LD` Specifies the linker command for the build host. By default, :term:`BUILD_LD` points to the GNU linker (ld) and passes as arguments the value of :term:`BUILD_LD_ARCH`, assuming :term:`BUILD_LD_ARCH` is set. + When building in the ``-native`` context, :term:`LD` is set to the value + of this variable by default. + :term:`BUILD_LD_ARCH` Specifies architecture-specific linker flags for the build host. By default, the value of :term:`BUILD_LD_ARCH` is empty. @@ -1045,6 +1097,34 @@ system and gives an overview of their function and contents. :term:`LDFLAGS` is set to the value of this variable by default. + :term:`BUILD_NM` + Specifies the architecture-specific utility to list symbols from object + files for the build host, derived in part from :term:`BUILD_PREFIX`:: + + BUILD_NM = "${BUILD_PREFIX}nm" + + When building in the ``-native`` context, :term:`NM` is set to the + value of this variable by default. + + :term:`BUILD_OBJCOPY` + Specifies the architecture-specific utility to copy object files for the + build host, derived in part from :term:`BUILD_PREFIX`:: + + BUILD_OBJCOPY = "${BUILD_PREFIX}objcopy" + + When building in the ``-native`` context, :term:`OBJCOPY` is set to the + value of this variable by default. + + :term:`BUILD_OBJDUMP` + Specifies the architecture-specific utility to display object files + information for the build host, derived in part from + :term:`BUILD_PREFIX`:: + + BUILD_OBJDUMP = "${BUILD_PREFIX}objdump" + + When building in the ``-native`` context, :term:`OBJDUMP` is set to the + value of this variable by default. + :term:`BUILD_OPTIMIZATION` Specifies the optimization flags passed to the C compiler when building for the build host or the SDK. The flags are passed through @@ -1065,12 +1145,33 @@ system and gives an overview of their function and contents. build system uses the :term:`BUILD_PREFIX` value to set the :term:`TARGET_PREFIX` when building for :ref:`ref-classes-native` recipes. + :term:`BUILD_RANLIB` + Specifies the architecture-specific utility to generate indexes for + archives for the build host, derived in part from :term:`BUILD_PREFIX`:: + + BUILD_RANLIB = "${BUILD_PREFIX}ranlib -D" + + When building in the ``-native`` context, :term:`RANLIB` is set to the + value of this variable by default. + + :term:`BUILD_READELF` + Specifies the architecture-specific utility to display information about + ELF files for the build host, derived in part from :term:`BUILD_PREFIX`:: + + BUILD_READELF = "${BUILD_PREFIX}readelf" + + When building in the ``-native`` context, :term:`READELF` is set to the + value of this variable by default. + :term:`BUILD_STRIP` Specifies the command to be used to strip debugging symbols from binaries produced for the build host. By default, :term:`BUILD_STRIP` points to ``${``\ :term:`BUILD_PREFIX`\ ``}strip``. + When building in the ``-native`` context, :term:`STRIP` is set to the + value of this variable by default. + :term:`BUILD_SYS` Specifies the system, including the architecture and the operating system, to use when building for the build host (i.e. when building @@ -2818,6 +2919,9 @@ system and gives an overview of their function and contents. :term:`FAKEROOTNOENV` See :term:`bitbake:FAKEROOTNOENV` in the BitBake manual. + :term:`FC` + The minimal command and arguments used to run the Fortran compiler. + :term:`FEATURE_PACKAGES` Defines one or more packages to include in an image when a specific item is included in :term:`IMAGE_FEATURES`. @@ -7289,6 +7393,9 @@ system and gives an overview of their function and contents. ":ref:`bitbake-user-manual/bitbake-user-manual-execution:dependencies`" sections in the BitBake User Manual for additional information on tasks and dependencies. + :term:`READELF` + The minimal command and arguments to run ``readelf``. + :term:`RECIPE_MAINTAINER` This variable defines the name and e-mail address of the maintainer of a recipe. Such information can be used by human users submitted changes,
These toolchain variables are used in a native context. Some of the BUILD_* variables missed documentation. Also, some of the base commands were also not there so document them (FC and READELF). Some of existing BUILD_* variable documentation were missing the note about their usage in a native context, so add it too so that all BUILD_* variables are documented the same way. [YOCTO #15719] Signed-off-by: Antonin Godard <antonin.godard@bootlin.com> --- documentation/ref-manual/variables.rst | 107 +++++++++++++++++++++++++ 1 file changed, 107 insertions(+)