[PATCH] libgloss: add a little build system generation documentation

[PATCH] libgloss: add a little build system generation documentation

[Mike Frysinger]

This is a bit of an abbreviated form of what's in the Newlib subdir,
but with emphasis on Libgloss-specific parts, and anything unique to
it.  I haven't put too much effort in.
---
 libgloss/doc/porting.texi | 50 ++++++++++++++++++++++++++++++++++++++-
 1 file changed, 49 insertions(+), 1 deletion(-)

diff --git a/libgloss/doc/porting.texi b/libgloss/doc/porting.texi
index 21b2f565a67f..5325fb2ed4fd 100644
--- a/libgloss/doc/porting.texi
+++ b/libgloss/doc/porting.texi
@@ -14,6 +14,10 @@
 @global@parindent=0pt
 @end iftex
 
+@set autoconf @ref{Top,,GNU Autoconf,autoconf}
+@set automake @ref{Top,,GNU Automake,automake}
+@set libtool @ref{Top,,GNU Libtool,libtool}
+
 @titlepage
 @title Embed With GNU
 @subtitle Porting The GNU Tools To Embedded Systems
@@ -242,7 +246,7 @@ mostly for Unix based systems.
 @section Configuring and building libgloss.
 
 Libgloss uses an autoconf based script to configure. Autoconf scripts
-are portable shell scripts that are generated from a configure.in file.
+are portable shell scripts that are generated from a configure.ac file.
 Configure input scripts are based themselves on m4. Most configure
 scripts run a series of tests to determine features the various
 supported features of the target. For features that can't be determined
@@ -353,6 +357,50 @@ the dependencies for the @code{all} target and add
 target.  Now, when libgloss is built and installed, support for your
 BSP will be installed as well.
 
+@node Build System Internals
+@section Build System Internals
+
+As noted previously, Libgloss uses GNU Autotools (@value{autoconf} &
+@value{automake}) to build.  @value{libtool} is not used as Libgloss only
+produces objects and static archives, and @value{automake} is capable of
+handling that.
+
+If you're editing any of these files and want to regenerate them, simply run
+@code{autoreconf}.  It will take care of the rest.
+
+Tool versions are strictly controlled.  You must use GNU Autoconf 2.69 and GNU
+Automake 1.15.1 to generate the build files.  If your system does not include
+them, you can manually download and install them into your home directory.
+
+All of the common configure logic lives in @file{configure.ac}.  It checks for
+supported targets and creates the makefiles.  Any architecture that wishes to
+run custom configure tests should store them in @file{acinclude.m4} in their
+respective subdirectory and then use @code{m4_include} in @file{configure.ac}.
+Make sure to avoid running excessive tests for all targets, and avoid using
+generic names that can collide with other architectures -- the build uses a
+flat namespace that is shared among everyone.
+
+Libgloss has partially converted to @value{automake}.  The top-level directory
+uses it with @file{Makefile.am}, as do a few subdirectories with their
+@file{Makefile.inc} fragments.  The other subdirectories still use hand written
+@file{Makefile.in} files.  One day, they should get converted over too.
+Patches welcome!
+
+For directories that have converted to @value{automake}, a non-recursive build
+is used.  That means only a single Makefile is created in the top-level, and no
+Makefiles are created in subdirectories.  Make must be run in the top-level at
+all times.
+
+The @file{config/*.mh} and @file{config/*.mt} files are only used by the non-
+Automake files (i.e., the @file{Makefile.in} files).  They can be ignored for
+any target that has migrated to @value{automake}.
+
+Libgloss automatically builds itself for all multilib configurations that the
+active toolchain supports.  This logic is provided by common code from the
+combined toolchain source tree.  This should @strong{not} be confused with the
+Libgloss-specific @file{multi-build.in} file.  That is used by a few ports to
+further produce multiple targets.
+
 @node GCC, Libraries, Libgloss, Top
 @chapter Porting GCC
 
-- 
2.34.1

Re: [PATCH] libgloss: add a little build system generation documentation

[Corinna Vinschen]

On Feb 24 23:45, Mike Frysinger wrote:
> This is a bit of an abbreviated form of what's in the Newlib subdir,
> but with emphasis on Libgloss-specific parts, and anything unique to
> it.  I haven't put too much effort in.
> ---
>  libgloss/doc/porting.texi | 50 ++++++++++++++++++++++++++++++++++++++-
>  1 file changed, 49 insertions(+), 1 deletion(-)

GTG

Thx,
Corinna

RE: [PATCH] libgloss: add a little build system generation documentation

[Tamar Christina]

Hello,

This commit seems to break the build:

make[3]: Entering directory '/newlib/aarch64-none-elf/libgloss'
  MAKEINFO /src-newlib/libgloss/doc/porting.info
/src-newlib/libgloss/doc/porting.texi:360: warning: node `Board support' is prev for `Build System Internals' in sectioning but not in menu
/src-newlib/libgloss/doc/porting.texi:360: warning: node `Libgloss' is up for `Build System Internals' in sectioning but not in menu
/src-newlib/libgloss/doc/porting.texi:87: node `Libgloss' lacks menu item for `Build System Internals' despite being its Up target
make[3]: *** [Makefile:1233: /src-newlib/libgloss/doc/porting.info] Error 1
make[3]: Leaving directory '/newlib/aarch64-none-elf/libgloss'
make[2]: *** [Makefile:1439: all-recursive] Error 1

Kind Regards,
Tamar

> -----Original Message-----
> From: Newlib <newlib-bounces+tamar.christina=arm.com@sourceware.org>
> On Behalf Of Corinna Vinschen
> Sent: Monday, February 28, 2022 10:39 AM
> To: newlib@sourceware.org
> Subject: Re: [PATCH] libgloss: add a little build system generation
> documentation
> 
> On Feb 24 23:45, Mike Frysinger wrote:
> > This is a bit of an abbreviated form of what's in the Newlib subdir,
> > but with emphasis on Libgloss-specific parts, and anything unique to
> > it.  I haven't put too much effort in.
> > ---
> >  libgloss/doc/porting.texi | 50
> > ++++++++++++++++++++++++++++++++++++++-
> >  1 file changed, 49 insertions(+), 1 deletion(-)
> 
> GTG
> 
> Thx,
> Corinna

Re: [PATCH] libgloss: add a little build system generation documentation

[Mike Frysinger]

[-- Attachment #1: Type: text/plain, Size: 1404 bytes --]

On 02 Mar 2022 13:10, Tamar Christina wrote:
> This commit seems to break the build:
> 
> make[3]: Entering directory '/newlib/aarch64-none-elf/libgloss'
>   MAKEINFO /src-newlib/libgloss/doc/porting.info
> /src-newlib/libgloss/doc/porting.texi:360: warning: node `Board support' is prev for `Build System Internals' in sectioning but not in menu
> /src-newlib/libgloss/doc/porting.texi:360: warning: node `Libgloss' is up for `Build System Internals' in sectioning but not in menu
> /src-newlib/libgloss/doc/porting.texi:87: node `Libgloss' lacks menu item for `Build System Internals' despite being its Up target
> make[3]: *** [Makefile:1233: /src-newlib/libgloss/doc/porting.info] Error 1
> make[3]: Leaving directory '/newlib/aarch64-none-elf/libgloss'
> make[2]: *** [Makefile:1439: all-recursive] Error 1

builds fine for me w/texinfo-6.8.  what version are you using ?

current texinfo guidelines is to omit the 2nd+ args for @node.
wonder if that would fix the build for you.
-mike

--- a/libgloss/doc/porting.texi
+++ b/libgloss/doc/porting.texi
@@ -311,7 +311,7 @@
 and uninstalled object tree. It also makes it easier to debug the other
 tools using libgloss's test suites.
 
-@node Board support, , Building libgloss, Libgloss
+@node Board support
 @section Adding Support for a New Board
 
 This section explains how to add support for a new board to libgloss.

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

Re: [PATCH] libgloss: add a little build system generation documentation

[Richard Earnshaw]

On 03/03/2022 04:22, Mike Frysinger wrote:
> On 02 Mar 2022 13:10, Tamar Christina wrote:
>> This commit seems to break the build:
>>
>> make[3]: Entering directory '/newlib/aarch64-none-elf/libgloss'
>>    MAKEINFO /src-newlib/libgloss/doc/porting.info
>> /src-newlib/libgloss/doc/porting.texi:360: warning: node `Board support' is prev for `Build System Internals' in sectioning but not in menu
>> /src-newlib/libgloss/doc/porting.texi:360: warning: node `Libgloss' is up for `Build System Internals' in sectioning but not in menu
>> /src-newlib/libgloss/doc/porting.texi:87: node `Libgloss' lacks menu item for `Build System Internals' despite being its Up target
>> make[3]: *** [Makefile:1233: /src-newlib/libgloss/doc/porting.info] Error 1
>> make[3]: Leaving directory '/newlib/aarch64-none-elf/libgloss'
>> make[2]: *** [Makefile:1439: all-recursive] Error 1
> 
> builds fine for me w/texinfo-6.8.  what version are you using ?

I think it fails with 6.7, at least that's what I have on my machine, 
where that's the standard version in Ubuntu-20.04.

> 
> current texinfo guidelines is to omit the 2nd+ args for @node.
> wonder if that would fix the build for you.
> -mike
> 
> --- a/libgloss/doc/porting.texi
> +++ b/libgloss/doc/porting.texi
> @@ -311,7 +311,7 @@
>   and uninstalled object tree. It also makes it easier to debug the other
>   tools using libgloss's test suites.
>   
> -@node Board support, , Building libgloss, Libgloss
> +@node Board support
>   @section Adding Support for a New Board
>   
>   This section explains how to add support for a new board to libgloss.

R.

RE: [PATCH] libgloss: add a little build system generation documentation

[Tamar Christina]

Indeed, it's failing with 6.7 on Ubuntu 20.04.

The patch didn't seem to help.

It did put up an additional warning with the patch

src-newlib/libgloss/doc/porting.texi:314: warning: node `Build System Internals' is next for `Board support' in sectioning but not in menu
src-newlib/libgloss/doc/porting.texi:360: warning: node `Board support' is prev for `Build System Internals' in sectioning but not in menu
src-newlib/libgloss/doc/porting.texi:360: warning: node `Libgloss' is up for `Build System Internals' in sectioning but not in menu
src-newlib/libgloss/doc/porting.texi:87: node `Libgloss' lacks menu item for `Build System Internals' despite being its Up target
make[3]: *** [Makefile:1233: src-newlib/libgloss/doc/porting.info] Error 1

first one is new.

Regards,
Tamar

> -----Original Message-----
> From: Richard Earnshaw <Richard.Earnshaw@foss.arm.com>
> Sent: Thursday, March 3, 2022 11:44 AM
> To: Tamar Christina <Tamar.Christina@arm.com>; newlib@sourceware.org
> Subject: Re: [PATCH] libgloss: add a little build system generation
> documentation
> 
> 
> 
> On 03/03/2022 04:22, Mike Frysinger wrote:
> > On 02 Mar 2022 13:10, Tamar Christina wrote:
> >> This commit seems to break the build:
> >>
> >> make[3]: Entering directory '/newlib/aarch64-none-elf/libgloss'
> >>    MAKEINFO /src-newlib/libgloss/doc/porting.info
> >> /src-newlib/libgloss/doc/porting.texi:360: warning: node `Board
> >> support' is prev for `Build System Internals' in sectioning but not
> >> in menu
> >> /src-newlib/libgloss/doc/porting.texi:360: warning: node `Libgloss'
> >> is up for `Build System Internals' in sectioning but not in menu
> >> /src-newlib/libgloss/doc/porting.texi:87: node `Libgloss' lacks menu
> >> item for `Build System Internals' despite being its Up target
> >> make[3]: *** [Makefile:1233: /src-newlib/libgloss/doc/porting.info]
> >> Error 1
> >> make[3]: Leaving directory '/newlib/aarch64-none-elf/libgloss'
> >> make[2]: *** [Makefile:1439: all-recursive] Error 1
> >
> > builds fine for me w/texinfo-6.8.  what version are you using ?
> 
> I think it fails with 6.7, at least that's what I have on my machine, where that's
> the standard version in Ubuntu-20.04.
> 
> >
> > current texinfo guidelines is to omit the 2nd+ args for @node.
> > wonder if that would fix the build for you.
> > -mike
> >
> > --- a/libgloss/doc/porting.texi
> > +++ b/libgloss/doc/porting.texi
> > @@ -311,7 +311,7 @@
> >   and uninstalled object tree. It also makes it easier to debug the other
> >   tools using libgloss's test suites.
> >
> > -@node Board support, , Building libgloss, Libgloss
> > +@node Board support
> >   @section Adding Support for a New Board
> >
> >   This section explains how to add support for a new board to libgloss.
> 
> R.

Re: [PATCH] libgloss: add a little build system generation documentation

[Stafford Horne]

On Thu, Mar 3, 2022 at 8:54 PM Tamar Christina <Tamar.Christina@arm.com> wrote:
>
> Indeed, it's failing with 6.7 on Ubuntu 20.04.
>
> The patch didn't seem to help.
>
> It did put up an additional warning with the patch
>
> src-newlib/libgloss/doc/porting.texi:314: warning: node `Build System Internals' is next for `Board support' in sectioning but not in menu
> src-newlib/libgloss/doc/porting.texi:360: warning: node `Board support' is prev for `Build System Internals' in sectioning but not in menu
> src-newlib/libgloss/doc/porting.texi:360: warning: node `Libgloss' is up for `Build System Internals' in sectioning but not in menu
> src-newlib/libgloss/doc/porting.texi:87: node `Libgloss' lacks menu item for `Build System Internals' despite being its Up target
> make[3]: *** [Makefile:1233: src-newlib/libgloss/doc/porting.info] Error 1
>
> first one is new.
>
> Regards,
> Tamar
>
> > -----Original Message-----
> > From: Richard Earnshaw <Richard.Earnshaw@foss.arm.com>
> > Sent: Thursday, March 3, 2022 11:44 AM
> > To: Tamar Christina <Tamar.Christina@arm.com>; newlib@sourceware.org
> > Subject: Re: [PATCH] libgloss: add a little build system generation
> > documentation
> >
> >
> >
> > On 03/03/2022 04:22, Mike Frysinger wrote:
> > > On 02 Mar 2022 13:10, Tamar Christina wrote:
> > >> This commit seems to break the build:
> > >>
> > >> make[3]: Entering directory '/newlib/aarch64-none-elf/libgloss'
> > >>    MAKEINFO /src-newlib/libgloss/doc/porting.info
> > >> /src-newlib/libgloss/doc/porting.texi:360: warning: node `Board
> > >> support' is prev for `Build System Internals' in sectioning but not
> > >> in menu
> > >> /src-newlib/libgloss/doc/porting.texi:360: warning: node `Libgloss'
> > >> is up for `Build System Internals' in sectioning but not in menu
> > >> /src-newlib/libgloss/doc/porting.texi:87: node `Libgloss' lacks menu
> > >> item for `Build System Internals' despite being its Up target
> > >> make[3]: *** [Makefile:1233: /src-newlib/libgloss/doc/porting.info]
> > >> Error 1
> > >> make[3]: Leaving directory '/newlib/aarch64-none-elf/libgloss'
> > >> make[2]: *** [Makefile:1439: all-recursive] Error 1
> > >
> > > builds fine for me w/texinfo-6.8.  what version are you using ?
> >
> > I think it fails with 6.7, at least that's what I have on my machine, where that's
> > the standard version in Ubuntu-20.04.
> >
> > >
> > > current texinfo guidelines is to omit the 2nd+ args for @node.
> > > wonder if that would fix the build for you.
> > > -mike
> > >
> > > --- a/libgloss/doc/porting.texi
> > > +++ b/libgloss/doc/porting.texi
> > > @@ -311,7 +311,7 @@
> > >   and uninstalled object tree. It also makes it easier to debug the other
> > >   tools using libgloss's test suites.
> > >
> > > -@node Board support, , Building libgloss, Libgloss
> > > +@node Board support
> > >   @section Adding Support for a New Board
> > >
> > >   This section explains how to add support for a new board to libgloss.
> >

I was getting the same failure, this patch works for me.

diff --git a/libgloss/doc/porting.texi b/libgloss/doc/porting.texi
index 5325fb2ed..7473c3706 100644
--- a/libgloss/doc/porting.texi
+++ b/libgloss/doc/porting.texi
@@ -136,6 +136,8 @@ new library is called Libgloss, for Gnu Low-level
OS support.
 * Building libgloss::           How to configure and built libgloss
                                 for a target.
 * Board support::               How to add support for a new board.
+
+* Build System Internals::      How the libgloss build system works.
 @end menu

 @node Supported targets, Building libgloss, Libgloss, Libgloss

Re: [PATCH] libgloss: add a little build system generation documentation

[Mike Frysinger]

[-- Attachment #1: Type: text/plain, Size: 1488 bytes --]

i've pushed this then
-mike

From 845515267b8dfb7198ae5ca9d4a30d58b2a3d995 Mon Sep 17 00:00:00 2001
From: Mike Frysinger <vapier@gentoo.org>
Date: Fri, 4 Mar 2022 01:04:25 -0500
Subject: [PATCH] libgloss: add new Build System Internals node to the menu

Seems that some versions of texinfo require the @menu to have all
entries at the top level, so add the new build one to it.
---
 libgloss/doc/porting.texi | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/libgloss/doc/porting.texi b/libgloss/doc/porting.texi
index 5325fb2ed4fd..496fae352148 100644
--- a/libgloss/doc/porting.texi
+++ b/libgloss/doc/porting.texi
@@ -136,6 +136,7 @@ new library is called Libgloss, for Gnu Low-level OS support.
 * Building libgloss::           How to configure and built libgloss
                                 for a target.
 * Board support::               How to add support for a new board.
+* Build System Internals::      How the libgloss build system works.
 @end menu
 
 @node Supported targets, Building libgloss, Libgloss, Libgloss
@@ -311,7 +312,7 @@ used. This is done so libgloss will build automatically with a fresh,
 and uninstalled object tree. It also makes it easier to debug the other
 tools using libgloss's test suites.
 
-@node Board support, , Building libgloss, Libgloss
+@node Board support
 @section Adding Support for a New Board
 
 This section explains how to add support for a new board to libgloss.
-- 
2.34.1

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]