From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from smtp.gentoo.org (woodpecker.gentoo.org [IPv6:2001:470:ea4a:1:5054:ff:fec7:86e4]) by sourceware.org (Postfix) with ESMTP id 6177D3858414 for ; Fri, 25 Feb 2022 04:45:01 +0000 (GMT) DMARC-Filter: OpenDMARC Filter v1.4.1 sourceware.org 6177D3858414 Authentication-Results: sourceware.org; dmarc=pass (p=none dis=none) header.from=gentoo.org Authentication-Results: sourceware.org; spf=pass smtp.mailfrom=gentoo.org Received: by smtp.gentoo.org (Postfix, from userid 559) id E611F342E6A; Fri, 25 Feb 2022 04:45:00 +0000 (UTC) From: Mike Frysinger To: newlib@sourceware.org Subject: [PATCH] libgloss: add a little build system generation documentation Date: Thu, 24 Feb 2022 23:45:01 -0500 Message-Id: <20220225044501.27831-1-vapier@gentoo.org> X-Mailer: git-send-email 2.34.1 MIME-Version: 1.0 Content-Transfer-Encoding: 8bit X-Spam-Status: No, score=-11.6 required=5.0 tests=BAYES_00, GIT_PATCH_0, KAM_DMARC_STATUS, SPF_HELO_PASS, SPF_PASS, TXREP, T_SCC_BODY_TEXT_LINE autolearn=ham autolearn_force=no version=3.4.4 X-Spam-Checker-Version: SpamAssassin 3.4.4 (2020-01-24) on server2.sourceware.org X-BeenThere: newlib@sourceware.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: Newlib mailing list List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Fri, 25 Feb 2022 04:45:07 -0000 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