path: root/meta/recipes-devtools/autoconf/autoconf/backports/0026-Modernize-INSTALL.patch

From a7421b411b4359b97528c8f4e9dd8abe82235813 Mon Sep 17 00:00:00 2001
From: Paul Eggert <eggert@cs.ucla.edu>
Date: Tue, 20 Jun 2023 13:23:19 -0700
Subject: [PATCH 26/29] Modernize INSTALL

Problem reported for gettext bootstrap by Julien Palard in:
https://savannah.gnu.org/bugs/?62196
* doc/install.texi: Give a brief info as to how to bootstrap,
on packages built from Git rather from a distribution tarball.
Remove aging details about c99, macOS, X, HP-UX, OSF/1, Solaris,
Haiku, sun4.  Improve documentation for enable/disable and
with/without options.

Upstream-Status: Backport
Signed-off-by: Khem Raj <raj.khem@gmail.com>
---
 doc/install.texi | 157 +++++++++++++++++++++--------------------------
 1 file changed, 70 insertions(+), 87 deletions(-)

diff --git a/doc/install.texi b/doc/install.texi
index e06689613..cec245fd0 100644
--- a/doc/install.texi
+++ b/doc/install.texi
@@ -18,9 +18,21 @@ warranty of any kind.
 @node Basic Installation
 @section Basic Installation
 
-Briefly, the shell command
-@samp{./configure@tie{}&& make@tie{}&& make@tie{}install}
-should configure, build, and install this package.  The following
+Briefly, the following shell commands:
+
+@example
+test -f configure || ./bootstrap
+./configure
+make
+make install
+@end example
+
+@noindent
+should configure, build, and install this package.
+The @command{./bootstrap} line is intended for developers;
+you can omit it when building from a distribution tarball.
+
+The following
 more-detailed instructions are generic; see the @file{README} file for
 instructions specific to this package.
 @ifclear autoconf
@@ -32,6 +44,17 @@ More recommendations for GNU packages can be found in
 @ref{Makefile Conventions, , Makefile Conventions, standards,
 GNU Coding Standards}.
 
+If the @command{bootstrap} shell script exists, it attempts to build the
+@command{configure} shell script and related files, perhaps by
+downloading other software components from the network, and by using
+developer tools that are less commonly installed.  Because the output of
+@command{bootstrap} is system-independent, it is normally run by a
+package developer so that its output can be put into the distribution
+tarball and ordinary builders and users need not run @command{bootstrap}.
+Some packages have commands like @command{./autopull.sh} and
+@command {./autogen.sh} that you can run instead of @command{./bootstrap},
+for more fine-grained control over bootstrapping.
+
 The @command{configure} shell script attempts to guess correct values
 for various system-dependent variables used during compilation.  It uses
 those values to create a @file{Makefile} in each directory of the
@@ -63,8 +86,15 @@ The simplest way to compile this package is:
 
 @enumerate
 @item
-@command{cd} to the directory containing the package's source code and type
-@samp{./configure} to configure the package for your system.
+@command{cd} to the directory containing the package's source code.
+
+@item
+If this is a developer checkout and file @samp{configure} does not yet exist,
+type @samp{./bootstrap} to create it.
+You may need special developer tools and network access to bootstrap.
+
+@item
+Type @samp{./configure} to configure the package for your system.
 
 Running @command{configure} might take a while.  While running, it prints some
 messages telling which features it is checking for.
@@ -124,7 +154,7 @@ parameters by setting variables in the command line or in the environment.
 Here is an example:
 
 @example
-./configure CC=c99 CFLAGS=-g LIBS=-lposix
+./configure CC=gcc CFLAGS=-g LIBS=-lposix
 @end example
 
 @xref{Defining Variables}, for more details.
@@ -148,21 +178,10 @@ architecture at a time in the source code directory.  After you have
 installed the package for one architecture, use @samp{make distclean}
 before reconfiguring for another architecture.
 
-On MacOS X 10.5 and later systems, you can create libraries and
-executables that work on multiple system types---known as @dfn{fat} or
-@dfn{universal} binaries---by specifying multiple @option{-arch} options
-to the compiler but only a single @option{-arch} option to the
-preprocessor.  Like this:
-
-@example
-./configure CC="gcc -arch i386 -arch x86_64 -arch ppc -arch ppc64" \
-            CXX="g++ -arch i386 -arch x86_64 -arch ppc -arch ppc64" \
-            CPP="gcc -E" CXXCPP="g++ -E"
-@end example
-
-This is not guaranteed to produce working output in all cases, you may
-have to build one architecture at a time and combine the results
-using the @command{lipo} tool if you have problems.
+Some platforms, notably macOS, support ``fat'' or ``universal'' binaries,
+where a single binary can execute on different architectures.
+On these platforms you can configure and compile just once,
+with options specific to that platform.
 
 @node Installation Names
 @section Installation Names
@@ -227,20 +246,16 @@ an extra prefix or suffix on their names by giving @command{configure}
 the option @option{--program-prefix=@var{PREFIX}} or
 @option{--program-suffix=@var{SUFFIX}}.
 
-Some packages pay attention to @option{--enable-@var{feature}} options
+Some packages pay attention to @option{--enable-@var{feature}}
+and @option{--disable-@var{feature}} options
 to @command{configure}, where @var{feature} indicates an optional part
 of the package.  They may also pay attention to
-@option{--with-@var{package}} options, where @var{package} is something
-like @samp{gnu-as} or @samp{x} (for the X Window System).  The
-@file{README} should mention any @option{--enable-} and @option{--with-}
+@option{--with-@var{package}} and @option{--without-@var{package}} options,
+where @var{package} is something like @samp{gnu-ld}.
+@samp{./configure --help} should mention the
+@option{--enable-...} and @option{--with-...}
 options that the package recognizes.
 
-For packages that use the X Window System, @command{configure} can
-usually find the X include and library files automatically, but if it
-doesn't, you can use the @command{configure} options
-@option{--x-includes=@var{dir}} and @option{--x-libraries=@var{dir}} to
-specify their locations.
-
 Some packages offer the ability to configure how verbose the execution
 of @command{make} will be.  For these packages, running
 @samp{./configure --enable-silent-rules} sets the default to minimal
@@ -248,53 +263,6 @@ output, which can be overridden with @code{make V=1}; while running
 @samp{./configure --disable-silent-rules} sets the default to verbose,
 which can be overridden with @code{make V=0}.
 
-@node Particular Systems
-@section Particular systems
-
-On HP-UX, the default C compiler is not ANSI C compatible.  If GNU CC is
-not installed, it is recommended to use the following options in order to
-use an ANSI C compiler:
-
-@example
-./configure CC="cc -Ae -D_XOPEN_SOURCE=500"
-@end example
-
-@noindent
-and if that doesn't work, install pre-built binaries of GCC for HP-UX.
-
-HP-UX @command{make} updates targets which have the same timestamps as
-their prerequisites, which makes it generally unusable when shipped
-generated files such as @command{configure} are involved.  Use GNU
-@command{make} instead.
-
-On OSF/1 a.k.a.@: Tru64, some versions of the default C compiler cannot
-parse its @code{<wchar.h>} header file.  The option @option{-nodtk} can be
-used as a workaround.  If GNU CC is not installed, it is therefore
-recommended to try
-
-@example
-./configure CC="cc"
-@end example
-
-@noindent
-and if that doesn't work, try
-
-@example
-./configure CC="cc -nodtk"
-@end example
-
-On Solaris, don't put @code{/usr/ucb} early in your @env{PATH}.  This
-directory contains several dysfunctional programs; working variants
-of these programs are available in @code{/usr/bin}.  So, if you need
-@code{/usr/ucb} in your @env{PATH}, put it @emph{after} @code{/usr/bin}.
-
-On Haiku, software installed for all users goes in @file{/boot/common},
-not @file{/usr/local}.  It is recommended to use the following options:
-
-@example
-./configure --prefix=/boot/common
-@end example
-
 @node System Type
 @section Specifying the System Type
 
@@ -304,7 +272,8 @@ will run on.  Usually, assuming the package is built to be run on the
 @emph{same} architectures, @command{configure} can figure that out, but
 if it prints a message saying it cannot guess the machine type, give it
 the @option{--build=@var{type}} option.  @var{type} can either be a
-short name for the system type, such as @samp{sun4}, or a canonical name
+short name like @samp{mingw64} for the system type, or a canonical name
+like @samp{x86_64-pc-linux-gnu}
 which has the form:
 
 @example
@@ -319,6 +288,7 @@ where @var{system} can have one of these forms:
 @var{kernel}-@var{os}
 @end example
 
+@noindent
 See the file @file{config.sub} for the possible values of each field.
 If @file{config.sub} isn't included in this package, then this package
 doesn't need to know the machine type.
@@ -405,13 +375,6 @@ traditionally @file{config.cache}.  @var{file} defaults to
 @itemx -C
 Alias for @option{--cache-file=config.cache}.
 
-@item --quiet
-@itemx --silent
-@itemx -q
-Do not print messages saying which checks are being made.  To suppress
-all normal output, redirect it to @file{/dev/null} (any error messages
-will still be shown).
-
 @item --srcdir=@var{dir}
 Look for the package's source code in directory @var{dir}.  Usually
 @command{configure} can determine that directory automatically.
@@ -421,13 +384,33 @@ Use @var{dir} as the installation prefix.  @ref{Installation Names}
 for more details, including other options available for fine-tuning
 the installation locations.
 
+@item --build=@var{type}
+Build for architecture @var{type}.  @ref{Specifying the System Type}
+for more details, including other system type options.
+
+@item --enable-@var{feature}
+@itemx --disable-@var{feature}
+Enable or disable the optional @var{feature}.  @xref{Optional Features}.
+
+@item --with-@var{package}
+@itemx --without-@var{package}
+Use or omit @var{package} when building.  @xref{Optional Features}.
+
+@item --quiet
+@itemx --silent
+@itemx -q
+Do not print messages saying which checks are being made.  To suppress
+all normal output, redirect it to @file{/dev/null} (any error messages
+will still be shown).
+
 @item --no-create
 @itemx -n
 Run the configure checks, but stop before creating any output files.
 @end table
 
 @noindent
-@command{configure} also accepts some other, not widely useful, options.
+@command{configure} also recognizes several environment variables,
+and accepts some other, less widely useful, options.
 Run @samp{configure --help} for more details.
 
 @c Local Variables:
-- 
2.41.0