diff options
Diffstat (limited to 'static/freebsd/man5/style.Makefile.5 3.html')
| -rw-r--r-- | static/freebsd/man5/style.Makefile.5 3.html | 168 |
1 files changed, 168 insertions, 0 deletions
diff --git a/static/freebsd/man5/style.Makefile.5 3.html b/static/freebsd/man5/style.Makefile.5 3.html new file mode 100644 index 00000000..6d8336bc --- /dev/null +++ b/static/freebsd/man5/style.Makefile.5 3.html @@ -0,0 +1,168 @@ +<table class="head"> + <tr> + <td class="head-ltitle">STYLE.MAKEFILE(5)</td> + <td class="head-vol">File Formats Manual</td> + <td class="head-rtitle">STYLE.MAKEFILE(5)</td> + </tr> +</table> +<div class="manual-text"> +<section class="Sh"> +<h1 class="Sh" id="NAME"><a class="permalink" href="#NAME">NAME</a></h1> +<p class="Pp"><code class="Nm">style.Makefile</code> — + <span class="Nd">FreeBSD Makefile style guide</span></p> +</section> +<section class="Sh"> +<h1 class="Sh" id="DESCRIPTION"><a class="permalink" href="#DESCRIPTION">DESCRIPTION</a></h1> +<p class="Pp">This file specifies the preferred style for makefiles in the + <span class="Ux">FreeBSD</span> source tree.</p> +<ul class="Bl-bullet"> + <li id=".PATH"><a class="permalink" href="#.PATH"><code class="Cm">.PATH</code></a>: + comes first if needed, and is spelled “<code class="Li">.PATH: + </code>”, with a single ASCII space after a colon. Do not use the + <var class="Va">VPATH</var> variable.</li> + <li>Special variables (i.e., <var class="Va">LIB</var>, + <var class="Va">SRCS</var>, <var class="Va">MLINKS</var>, etc.) are listed + in order of “product”, then building and installing a + binary. Special variables may also be listed in “build” + order: i.e., ones for the primary program (or library) first. The general + “product” order is: + <var class="Va">PROG</var>/[<var class="Va">SH</var>]<var class="Va">LIB</var>/<var class="Va">SCRIPTS</var> + <var class="Va">FILES</var> <var class="Va">LINKS</var> + <var class="Va">MAN</var> <var class="Va">MLINKS</var> + <var class="Va">INCS</var> <var class="Va">SRCS</var> + <var class="Va">WARNS</var> <var class="Va">CSTD</var> + <var class="Va">CFLAGS</var> <var class="Va">DPADD</var> + <var class="Va">LDADD</var>. The general “build” order is: + <var class="Va">PROG</var>/[<var class="Va">SH</var>]<var class="Va">LIB</var>/<var class="Va">SCRIPTS</var> + <var class="Va">SRCS</var> <var class="Va">WARNS</var> + <var class="Va">CSTD</var> <var class="Va">CFLAGS</var> + <var class="Va">DPADD</var> <var class="Va">LDADD</var> + <var class="Va">INCS</var> <var class="Va">FILES</var> + <var class="Va">LINKS</var> <var class="Va">MAN</var> + <var class="Va">MLINKS</var>.</li> + <li>Omit <var class="Va">SRCS</var> when using + <code class="In"><<a class="In">bsd.prog.mk</a>></code> and there is + a single source file named the same as the + <var class="Va">PROG</var>.</li> + <li>Omit <var class="Va">MAN</var> when using + <code class="In"><<a class="In">bsd.prog.mk</a>></code> and the + manual page is named the same as the <var class="Va">PROG</var>, and is in + section 1.</li> + <li>All variable assignments are spelled + “<var class="Va">VAR</var><code class="Ic">=</code>”, i.e., + no space between the variable name and the <code class="Ic">=</code>. Keep + values sorted alphabetically, if possible.</li> + <li id="__">Variables are expanded with + <a class="permalink" href="#__"><b class="Sy">{}</b></a>, not + <a class="permalink" href="#()"><b class="Sy" id="()">()</b></a>. Such as + <var class="Va">${VARIABLE}</var>.</li> + <li>Do not use <code class="Ic">+=</code> to set variables that are only set + once (or to set variables for the first time).</li> + <li>Do not use vertical whitespace in simple makefiles, but do use it to group + locally related things in more complex/longer ones.</li> + <li id="WARNS"><var class="Va">WARNS</var> comes before + <var class="Va">CFLAGS</var>, as it is basically a + <var class="Va">CFLAGS</var> modifier. It comes before + <var class="Va">CFLAGS</var> rather than after + <var class="Va">CFLAGS</var> so it does not get lost in a sea of + <var class="Va">CFLAGS</var> statements as <var class="Va">WARNS</var> is + an important thing. The usage of <var class="Va">WARNS</var> is spelled + “<code class="Li">WARNS?= </code>”, so that it may be + overridden on the command line or in <a class="Xr">make.conf(5)</a>.</li> + <li>“<code class="Li">MK_WERROR=no</code>” should not be used, + it defeats the purpose of <var class="Va">WARNS</var>. It should only be + used on the command line and in special circumstances.</li> + <li id="CFLAGS"><var class="Va">CFLAGS</var> is spelled + “<code class="Li">CFLAGS+= </code>”.</li> + <li>Listing <code class="Fl">-D</code>'s before <code class="Fl">-I</code>'s + in <var class="Va">CFLAGS</var> is preferred for alphabetical ordering and + to make <code class="Fl">-D</code>'s easier to see. The + <code class="Fl">-D</code>'s often affect conditional compilation, and + <code class="Fl">-I</code>'s tend to be quite long. Split long + <var class="Va">CFLAGS</var> settings between the + <code class="Fl">-D</code>'s and <code class="Fl">-I</code>'s.</li> + <li>Lists that span more than one line should be formatted as follows: + <div class="Bd Pp Bd-indent Li"> + <pre>SRCS+=<SP>\ +<TAB>main.c<SP>\ +<TAB>trace.c<SP>\ +<TAB>zoo.c \ + </pre> + </div> + Specifically, the last item in the list should have a trailing '\'. This is + to avoid causing a "false diff" or "false blame" when + a new item is appended at the end. In general the list should be English + language alphabetized. A list of libraries or header inclusion paths are + notable exceptions if needed for proper building.</li> + <li>Do not use GCCisms (such as <code class="Fl">-g</code> and + <code class="Fl">-Wall</code>) in <var class="Va">CFLAGS</var>.</li> + <li>Typically, there is one ASCII tab between + <var class="Va">VAR</var><code class="Ic">=</code> and the value in order + to start the value in column 9. An ASCII space is allowed for variable + names that extend beyond column 9. A lack of whitespace is also allowed + for very long variable names.</li> + <li id=".include"><a class="permalink" href="#.include"><code class="Ic">.include</code></a> + <code class="In"><<a class="In">bsd.*.mk</a>></code> goes last.</li> + <li>Do not use anachronisms like <var class="Va">$<</var> and + <var class="Va">$@</var>. Instead use <var class="Va">${.IMPSRC}</var> or + <var class="Va">${.ALLSRC}</var> and + <var class="Va">${.TARGET}</var>.</li> + <li>To not build the “foo” part of the base system, use + <var class="Va">NO_FOO</var>, not <var class="Va">NOFOO</var>.</li> + <li>To optionally build something in the base system, spell the knob + <var class="Va">WITH_FOO</var> not <var class="Va">WANT_FOO</var> or + <var class="Va">USE_FOO</var>. The latter are reserved for the + <span class="Ux">FreeBSD</span> Ports Collection.</li> + <li id="defined">For variables that are only checked with + <a class="permalink" href="#defined"><code class="Fn">defined</code></a>(), + do not provide any fake value.</li> +</ul> +</section> +<section class="Sh"> +<h1 class="Sh" id="EXAMPLES"><a class="permalink" href="#EXAMPLES">EXAMPLES</a></h1> +<p class="Pp">The simplest program <span class="Pa">Makefile</span> is:</p> +<div class="Bd Pp Bd-indent Li"> +<pre>PROG= foo + +.include <bsd.prog.mk></pre> +</div> +<p class="Pp">The simplest library <span class="Pa">Makefile</span> is:</p> +<div class="Bd Pp Bd-indent Li"> +<pre>LIB= foo +SHLIB_MAJOR= 1 +MAN= libfoo.3 +SRCS= foo.c + +.include <bsd.lib.mk></pre> +</div> +</section> +<section class="Sh"> +<h1 class="Sh" id="SEE_ALSO"><a class="permalink" href="#SEE_ALSO">SEE + ALSO</a></h1> +<p class="Pp"><a class="Xr">make(1)</a>, <a class="Xr">make.conf(5)</a>, + <a class="Xr">style(9)</a></p> +</section> +<section class="Sh"> +<h1 class="Sh" id="HISTORY"><a class="permalink" href="#HISTORY">HISTORY</a></h1> +<p class="Pp">This manual page is inspired from the <a class="Xr">style(9)</a> + manual page and first appeared in <span class="Ux">FreeBSD 5.1</span>.</p> +</section> +<section class="Sh"> +<h1 class="Sh" id="AUTHORS"><a class="permalink" href="#AUTHORS">AUTHORS</a></h1> +<p class="Pp"><span class="An">David O'Brien</span> + ⟨deo@NUXI.org⟩</p> +</section> +<section class="Sh"> +<h1 class="Sh" id="BUGS"><a class="permalink" href="#BUGS">BUGS</a></h1> +<p class="Pp">There are few hard and fast style rules here. The desire to + express a logical grouping sometimes means not obeying some of the above. + The style of many things is too dependent on the context of the whole + makefile, or the lines surrounding it.</p> +</section> +</div> +<table class="foot"> + <tr> + <td class="foot-date">October 29, 2025</td> + <td class="foot-os">FreeBSD 15.0</td> + </tr> +</table> |