new repository

1 files changed, 36 insertions, 0 deletions

diff --git a/devdocs/gnu_make/catalogue-of-rules.html b/devdocs/gnu_make/catalogue-of-rules.html
new file mode 100644
index 00000000..9ce216e8
--- /dev/null
+++ b/devdocs/gnu_make/catalogue-of-rules.html
@@ -0,0 +1,36 @@
+  <h1 class="section">Catalogue of Built-In Rules</h1>   <p>Here is a catalogue of predefined implicit rules which are always available unless the makefile explicitly overrides or cancels them. See <a href="canceling-rules">Canceling Implicit Rules</a>, for information on canceling or overriding an implicit rule. The ‘<samp>-r</samp>’ or ‘<samp>--no-builtin-rules</samp>’ option cancels all predefined rules. </p> <p>This manual only documents the default rules available on POSIX-based operating systems. Other operating systems, such as VMS, Windows, OS/2, etc. may have different sets of default rules. To see the full list of default rules and variables available in your version of GNU <code>make</code>, run ‘<samp>make -p</samp>’ in a directory with no makefile. </p> <p>Not all of these rules will always be defined, even when the ‘<samp>-r</samp>’ option is not given. Many of the predefined implicit rules are implemented in <code>make</code> as suffix rules, so which ones will be defined depends on the <em>suffix list</em> (the list of prerequisites of the special target <code>.SUFFIXES</code>). The default suffix list is: <code>.out</code>, <code>.a</code>, <code>.ln</code>, <code>.o</code>, <code>.c</code>, <code>.cc</code>, <code>.C</code>, <code>.cpp</code>, <code>.p</code>, <code>.f</code>, <code>.F</code>, <code>.m</code>, <code>.r</code>, <code>.y</code>, <code>.l</code>, <code>.ym</code>, <code>.lm</code>, <code>.s</code>, <code>.S</code>, <code>.mod</code>, <code>.sym</code>, <code>.def</code>, <code>.h</code>, <code>.info</code>, <code>.dvi</code>, <code>.tex</code>, <code>.texinfo</code>, <code>.texi</code>, <code>.txinfo</code>, <code>.w</code>, <code>.ch</code> <code>.web</code>, <code>.sh</code>, <code>.elc</code>, <code>.el</code>. All of the implicit rules described below whose prerequisites have one of these suffixes are actually suffix rules. If you modify the suffix list, the only predefined suffix rules in effect will be those named by one or two of the suffixes that are on the list you specify; rules whose suffixes fail to be on the list are disabled. See <a href="suffix-rules">Old-Fashioned Suffix Rules</a>, for full details on suffix rules. </p> <dl compact> <dt>Compiling C programs</dt> <dd>
+     <p><samp><var>n</var>.o</samp> is made automatically from <samp><var>n</var>.c</samp> with a recipe of the form ‘<samp>$(CC) $(CPPFLAGS) $(CFLAGS) <span class="nolinebreak">-c</span></samp>’. </p> </dd> <dt>Compiling C++ programs</dt> <dd>
+     <p><samp><var>n</var>.o</samp> is made automatically from <samp><var>n</var>.cc</samp>, <samp><var>n</var>.cpp</samp>, or <samp><var>n</var>.C</samp> with a recipe of the form ‘<samp>$(CXX) $(CPPFLAGS) $(CXXFLAGS) <span class="nolinebreak">-c</span></samp>’. We encourage you to use the suffix ‘<samp>.cc</samp>’ or ‘<samp>.cpp</samp>’ for C++ source files instead of ‘<samp>.C</samp>’ to better support case-insensitive file systems. </p> </dd> <dt>Compiling Pascal programs</dt> <dd>
+   <p><samp><var>n</var>.o</samp> is made automatically from <samp><var>n</var>.p</samp> with the recipe ‘<samp>$(PC) $(PFLAGS) -c</samp>’. </p> </dd> <dt>Compiling Fortran and Ratfor programs</dt> <dd>
+      <p><samp><var>n</var>.o</samp> is made automatically from <samp><var>n</var>.r</samp>, <samp><var>n</var>.F</samp> or <samp><var>n</var>.f</samp> by running the Fortran compiler. The precise recipe used is as follows: </p> <dl compact> <dt id=".f">‘<samp>.f</samp>’</dt> <dd><p>‘<samp>$(FC) $(FFLAGS) -c</samp>’. </p></dd> <dt id=".F">‘<samp>.F</samp>’</dt> <dd><p>‘<samp>$(FC) $(FFLAGS) $(CPPFLAGS) -c</samp>’. </p></dd> <dt id=".r">‘<samp>.r</samp>’</dt> <dd><p>‘<samp>$(FC) $(FFLAGS) $(RFLAGS) -c</samp>’. </p></dd> </dl> </dd> <dt>Preprocessing Fortran and Ratfor programs</dt> <dd>
+<p><samp><var>n</var>.f</samp> is made automatically from <samp><var>n</var>.r</samp> or <samp><var>n</var>.F</samp>. This rule runs just the preprocessor to convert a Ratfor or preprocessable Fortran program into a strict Fortran program. The precise recipe used is as follows: </p> <dl compact> <dt id=".F">‘<samp>.F</samp>’</dt> <dd><p>‘<samp>$(FC) $(CPPFLAGS) $(FFLAGS) -F</samp>’. </p></dd> <dt id=".r">‘<samp>.r</samp>’</dt> <dd><p>‘<samp>$(FC) $(FFLAGS) $(RFLAGS) -F</samp>’. </p></dd> </dl> </dd> <dt>Compiling Modula-2 programs</dt> <dd>
+     <p><samp><var>n</var>.sym</samp> is made from <samp><var>n</var>.def</samp> with a recipe of the form ‘<samp>$(M2C) $(M2FLAGS) $(DEFFLAGS)</samp>’. <samp><var>n</var>.o</samp> is made from <samp><var>n</var>.mod</samp>; the form is: ‘<samp>$(M2C) $(M2FLAGS) $(MODFLAGS)</samp>’. </p> </dd> <dt>Assembling and preprocessing assembler programs</dt> <dd>
+   <p><samp><var>n</var>.o</samp> is made automatically from <samp><var>n</var>.s</samp> by running the assembler, <code>as</code>. The precise recipe is ‘<samp>$(AS) $(ASFLAGS)</samp>’. </p>  <p><samp><var>n</var>.s</samp> is made automatically from <samp><var>n</var>.S</samp> by running the C preprocessor, <code>cpp</code>. The precise recipe is ‘<samp>$(CPP) $(CPPFLAGS)</samp>’. </p> </dd> <dt>Linking a single object file</dt> <dd>
+   <p><samp><var>n</var></samp> is made automatically from <samp><var>n</var>.o</samp> by running the C compiler to link the program. The precise recipe used is ‘<samp>$(CC) $(LDFLAGS) <var>n</var>.o $(LOADLIBES) $(LDLIBS)</samp>’. </p> <p>This rule does the right thing for a simple program with only one source file. It will also do the right thing if there are multiple object files (presumably coming from various other source files), one of which has a name matching that of the executable file. Thus, </p> <div class="example"> <pre class="example">x: y.o z.o
+</pre>
+</div> <p>when <samp>x.c</samp>, <samp>y.c</samp> and <samp>z.c</samp> all exist will execute: </p> <div class="example"> <pre class="example">cc -c x.c -o x.o
+cc -c y.c -o y.o
+cc -c z.c -o z.o
+cc x.o y.o z.o -o x
+rm -f x.o
+rm -f y.o
+rm -f z.o
+</pre>
+</div> <p>In more complicated cases, such as when there is no object file whose name derives from the executable file name, you must write an explicit recipe for linking. </p> <p>Each kind of file automatically made into ‘<samp>.o</samp>’ object files will be automatically linked by using the compiler (‘<samp>$(CC)</samp>’, ‘<samp>$(FC)</samp>’ or ‘<samp>$(PC)</samp>’; the C compiler ‘<samp>$(CC)</samp>’ is used to assemble ‘<samp>.s</samp>’ files) without the ‘<samp>-c</samp>’ option. This could be done by using the ‘<samp>.o</samp>’ object files as intermediates, but it is faster to do the compiling and linking in one step, so that’s how it’s done. </p> </dd> <dt>Yacc for C programs</dt> <dd>
+   <p><samp><var>n</var>.c</samp> is made automatically from <samp><var>n</var>.y</samp> by running Yacc with the recipe ‘<samp>$(YACC) $(YFLAGS)</samp>’. </p> </dd> <dt>Lex for C programs</dt> <dd>
+   <p><samp><var>n</var>.c</samp> is made automatically from <samp><var>n</var>.l</samp> by running Lex. The actual recipe is ‘<samp>$(LEX) $(LFLAGS)</samp>’. </p> </dd> <dt>Lex for Ratfor programs</dt> <dd>
+<p><samp><var>n</var>.r</samp> is made automatically from <samp><var>n</var>.l</samp> by running Lex. The actual recipe is ‘<samp>$(LEX) $(LFLAGS)</samp>’. </p> <p>The convention of using the same suffix ‘<samp>.l</samp>’ for all Lex files regardless of whether they produce C code or Ratfor code makes it impossible for <code>make</code> to determine automatically which of the two languages you are using in any particular case. If <code>make</code> is called upon to remake an object file from a ‘<samp>.l</samp>’ file, it must guess which compiler to use. It will guess the C compiler, because that is more common. If you are using Ratfor, make sure <code>make</code> knows this by mentioning <samp><var>n</var>.r</samp> in the makefile. Or, if you are using Ratfor exclusively, with no C files, remove ‘<samp>.c</samp>’ from the list of implicit rule suffixes with: </p> <div class="example"> <pre class="example">.SUFFIXES:
+.SUFFIXES: .o .r .f .l …
+</pre>
+</div> </dd> <dt>Making Lint Libraries from C, Yacc, or Lex programs</dt> <dd>
+   <p><samp><var>n</var>.ln</samp> is made from <samp><var>n</var>.c</samp> by running <code>lint</code>. The precise recipe is ‘<samp>$(LINT) $(LINTFLAGS) $(CPPFLAGS) <span class="nolinebreak">-i</span></samp>’. The same recipe is used on the C code produced from <samp><var>n</var>.y</samp> or <samp><var>n</var>.l</samp>. </p> </dd> <dt>TeX and Web</dt> <dd>
+            <p><samp><var>n</var>.dvi</samp> is made from <samp><var>n</var>.tex</samp> with the recipe ‘<samp>$(TEX)</samp>’. <samp><var>n</var>.tex</samp> is made from <samp><var>n</var>.web</samp> with ‘<samp>$(WEAVE)</samp>’, or from <samp><var>n</var>.w</samp> (and from <samp><var>n</var>.ch</samp> if it exists or can be made) with ‘<samp>$(CWEAVE)</samp>’. <samp><var>n</var>.p</samp> is made from <samp><var>n</var>.web</samp> with ‘<samp>$(TANGLE)</samp>’ and <samp><var>n</var>.c</samp> is made from <samp><var>n</var>.w</samp> (and from <samp><var>n</var>.ch</samp> if it exists or can be made) with ‘<samp>$(CTANGLE)</samp>’. </p> </dd> <dt>Texinfo and Info</dt> <dd>
+        <p><samp><var>n</var>.dvi</samp> is made from <samp><var>n</var>.texinfo</samp>, <samp><var>n</var>.texi</samp>, or <samp><var>n</var>.txinfo</samp>, with the recipe ‘<samp>$(TEXI2DVI) <span class="nolinebreak">$(TEXI2DVI_FLAGS)</span></samp>’. <samp><var>n</var>.info</samp> is made from <samp><var>n</var>.texinfo</samp>, <samp><var>n</var>.texi</samp>, or <samp><var>n</var>.txinfo</samp>, with the recipe ‘<samp>$(MAKEINFO) <span class="nolinebreak">$(MAKEINFO_FLAGS)</span></samp>’. </p> </dd> <dt>RCS</dt> <dd>
+   <p>Any file <samp><var>n</var></samp> is extracted if necessary from an RCS file named either <samp><var>n</var>,v</samp> or <samp>RCS/<var>n</var>,v</samp>. The precise recipe used is ‘<samp>$(CO) $(COFLAGS)</samp>’. <samp><var>n</var></samp> will not be extracted from RCS if it already exists, even if the RCS file is newer. The rules for RCS are terminal (see <a href="match_002danything-rules">Match-Anything Pattern Rules</a>), so RCS files cannot be generated from another source; they must actually exist. </p> </dd> <dt>SCCS</dt> <dd>
+   <p>Any file <samp><var>n</var></samp> is extracted if necessary from an SCCS file named either <samp>s.<var>n</var></samp> or <samp>SCCS/s.<var>n</var></samp>. The precise recipe used is ‘<samp>$(GET) $(GFLAGS)</samp>’. The rules for SCCS are terminal (see <a href="match_002danything-rules">Match-Anything Pattern Rules</a>), so SCCS files cannot be generated from another source; they must actually exist. </p>  <p>For the benefit of SCCS, a file <samp><var>n</var></samp> is copied from <samp><var>n</var>.sh</samp> and made executable (by everyone). This is for shell scripts that are checked into SCCS. Since RCS preserves the execution permission of a file, you do not need to use this feature with RCS. </p> <p>We recommend that you avoid using of SCCS. RCS is widely held to be superior, and is also free. By choosing free software in place of comparable (or inferior) proprietary software, you support the free software movement. </p>
+</dd> </dl> <p>Usually, you want to change only the variables listed in the table above, which are documented in the following section. </p> <p>However, the recipes in built-in implicit rules actually use variables such as <code>COMPILE.c</code>, <code>LINK.p</code>, and <code>PREPROCESS.S</code>, whose values contain the recipes listed above. </p> <p><code>make</code> follows the convention that the rule to compile a <samp>.<var>x</var></samp> source file uses the variable <code>COMPILE.<var>x</var></code>. Similarly, the rule to produce an executable from a <samp>.<var>x</var></samp> file uses <code>LINK.<var>x</var></code>; and the rule to preprocess a <samp>.<var>x</var></samp> file uses <code>PREPROCESS.<var>x</var></code>. </p>  <p>Every rule that produces an object file uses the variable <code>OUTPUT_OPTION</code>. <code>make</code> defines this variable either to contain ‘<samp>-o $@</samp>’, or to be empty, depending on a compile-time option. You need the ‘<samp>-o</samp>’ option to ensure that the output goes into the right file when the source file is in a different directory, as when using <code>VPATH</code> (see <a href="directory-search">Directory Search</a>). However, compilers on some systems do not accept a ‘<samp>-o</samp>’ switch for object files. If you use such a system, and use <code>VPATH</code>, some compilations will put their output in the wrong place. A possible workaround for this problem is to give <code>OUTPUT_OPTION</code> the value ‘<samp>; mv $*.o $@</samp>’. </p><div class="_attribution">
+  <p class="_attribution-p">
+    Copyright © 1988, 1989, 1990, 1991, 1992, 1993, 1994, 1995, 1996, 1997, 1998, 1999, 2000, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011, 2012, 2013, 2014, 2015, 2016, 2017, 2018, 2019, 2020, 2021, 2022 Free Software Foundation, Inc. <br>Licensed under the GNU Free Documentation License.<br>
+    <a href="https://www.gnu.org/software/make/manual/html_node/Catalogue-of-Rules.html" class="_attribution-link">https://www.gnu.org/software/make/manual/html_node/Catalogue-of-Rules.html</a>
+  </p>
+</div>