From owner-svn-src-projects@FreeBSD.ORG Fri Aug 7 01:46:08 2009 Return-Path: Delivered-To: svn-src-projects@freebsd.org Received: from mx1.freebsd.org (mx1.freebsd.org [IPv6:2001:4f8:fff6::34]) by hub.freebsd.org (Postfix) with ESMTP id 957B5106566C; Fri, 7 Aug 2009 01:46:08 +0000 (UTC) (envelope-from rodrigc@FreeBSD.org) Received: from svn.freebsd.org (svn.freebsd.org [IPv6:2001:4f8:fff6::2c]) by mx1.freebsd.org (Postfix) with ESMTP id 8327B8FC1E; Fri, 7 Aug 2009 01:46:08 +0000 (UTC) Received: from svn.freebsd.org (localhost [127.0.0.1]) by svn.freebsd.org (8.14.3/8.14.3) with ESMTP id n771k8iP071595; Fri, 7 Aug 2009 01:46:08 GMT (envelope-from rodrigc@svn.freebsd.org) Received: (from rodrigc@localhost) by svn.freebsd.org (8.14.3/8.14.3/Submit) id n771k8XL071593; Fri, 7 Aug 2009 01:46:08 GMT (envelope-from rodrigc@svn.freebsd.org) Message-Id: <200908070146.n771k8XL071593@svn.freebsd.org> From: Craig Rodrigues Date: Fri, 7 Aug 2009 01:46:08 +0000 (UTC) To: src-committers@freebsd.org, svn-src-projects@freebsd.org X-SVN-Group: projects MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Cc: Subject: svn commit: r196084 - projects/jbuild/usr.bin/jbuild X-BeenThere: svn-src-projects@freebsd.org X-Mailman-Version: 2.1.5 Precedence: list List-Id: "SVN commit messages for the src " projects" tree" List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Fri, 07 Aug 2009 01:46:09 -0000 Author: rodrigc Date: Fri Aug 7 01:46:08 2009 New Revision: 196084 URL: http://svn.freebsd.org/changeset/base/196084 Log: Add first draft of jbuild(1) man page. Added: projects/jbuild/usr.bin/jbuild/jbuild.1 Added: projects/jbuild/usr.bin/jbuild/jbuild.1 ============================================================================== --- /dev/null 00:00:00 1970 (empty, because file is newly added) +++ projects/jbuild/usr.bin/jbuild/jbuild.1 Fri Aug 7 01:46:08 2009 (r196084) @@ -0,0 +1,1786 @@ +.\" Copyright (c) 1990, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. All advertising materials mentioning features or use of this software +.\" must display the following acknowledgement: +.\" This product includes software developed by the University of +.\" California, Berkeley and its contributors. +.\" 4. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" @(#)make.1 8.8 (Berkeley) 6/13/95 +.\" $FreeBSD$ +.\" +.Dd August 6, 2009 +.Dt JBUILD 1 +.Os +.Sh NAME +.Nm jbuild +.Nd maintain program dependencies +.Sh SYNOPSIS +.Nm +.Op Fl ABPSXeiknpqrstv +.Op Fl C Ar directory +.Op Fl D Ar variable +.Op Fl d Ar flags +.Op Fl E Ar variable +.Op Fl f Ar makefile +.Op Fl I Ar directory +.Bk -words +.Op Fl j Ar max_jobs +.Op Fl m Ar directory +.Ek +.Op Fl V Ar variable +.Op Fl x Ar warning_options +.Op Ar variable Ns No = Ns Ar value +.Op Ar target ... +.Sh DESCRIPTION +The +.Nm +utility is a program designed to simplify the maintenance of other programs. +Its input is a list of specifications +describing dependency relationships between the generation of +files and programs. +.Pp +First of all, the initial list of specifications will be read +from the system makefile, +.Pa sys.mk , +unless inhibited with the +.Fl r +option. +The standard +.Pa sys.mk +as shipped with +.Fx +also handles +.Xr make.conf 5 , +the default path to which +can be altered via the +.Nm +variable +.Va __MAKE_CONF . +.Pp +Then the first +.Pa Buildfile , +that can be found in the current directory +or search path (see the +.Fl I +option) +will be read for the main list of dependency specifications. +A different Buildfile or list of them can be supplied via the +.Fl f +option(s). +Finally, if the file +.Pa .depend +can be found in any of the aforesaid locations, it will also be read (see +.Xr mkdep 1 ) . +.Pp +The options are as follows: +.Bl -tag -width Ds +.It Fl A +Make archive errors non-fatal, causing +.Nm +to just skip the remainder +or all of the archive and continue after printing a message. +.It Fl B +Try to be backwards compatible by executing a single shell per command and +by executing the commands to make the sources of a dependency line in sequence. +This is turned on by default unless +.Fl j +is used. +.It Fl C Ar directory +Change to +.Ar directory +before reading the Buildfiles or doing anything else. +If multiple +.Fl C +options are specified, each is interpreted relative to the previous one: +.Fl C Pa / Fl C Pa etc +is equivalent to +.Fl C Pa /etc . +.It Fl D Ar variable +Define +.Ar variable +to be 1, in the global context. +.It Fl d Ar flags +Turn on debugging, and specify which portions of +.Nm +are to print debugging information. +Argument +.Ar flags +is one or more of the following: +.Bl -tag -width Ds +.It Ar A +Print all possible debugging information; +equivalent to specifying all of the debugging flags. +.It Ar a +Print debugging information about archive searching and caching. +.It Ar c +Print debugging information about conditional evaluation. +.It Ar d +Print debugging information about directory searching and caching. +.It Ar f +Print debugging information about the execution of for loops. +.It Ar "g1" +Print the input graph before making anything. +.It Ar "g2" +Print the input graph after making everything, or before exiting +on error. +.It Ar j +Print debugging information about running multiple shells. +.It Ar l +Print commands in Buildfiles regardless of whether or not they are prefixed +by @ or other "quiet" flags. +Also known as "loud" behavior. +.It Ar m +Print debugging information about making targets, including modification +dates. +.It Ar s +Print debugging information about suffix-transformation rules. +.It Ar t +Print debugging information about target list maintenance. +.It Ar v +Print debugging information about variable assignment. +.El +.It Fl E Ar variable +Specify a variable whose environment value (if any) will override +macro assignments within Buildfiles. +.It Fl e +Specify that environment values override macro assignments within +makefiles for all variables. +.It Fl f Ar Buildfile +Specify a Buildfile to read instead of the default one. +If +.Ar Buildfile +is not an absolute pathname, +.Nm +will search for it as described above. +In case +.Ar Buildfile +is +.Sq Fl , +standard input is read. +Multiple +.Fl f +options can be supplied, +and the makefiles will be read in that order. +Unlike the other command-line options, +.Fl f +is neither stored in +.Va .MAKEFLAGS +nor pushed down to sub-makes via +.Ev MAKEFLAGS . +See below for more details on these variables. +.It Fl I Ar directory +Specify a directory in which to search for Buildfiles and included Buildfiles. +Multiple +.Fl I +options can be specified to form a search path. +The system makefile directory (or directories, see the +.Fl m +option) is automatically appended at the tail of this path. +.It Fl i +Ignore non-zero exit of shell commands in the makefile. +Equivalent to specifying +.Sq Ic \- +before each command line in the makefile. +.It Fl j Ar max_jobs +Specify the maximum number of jobs that +.Nm +may have running at any one time. +Turns compatibility mode off, unless the +.Fl B +flag is also specified. +.It Fl k +Continue processing after errors are encountered, but only on those targets +that do not depend on the target whose creation caused the error. +.It Fl m Ar directory +Specify a directory in which to search for +the system makefile and makefiles included via the <...> style. +Multiple +.Fl m +options can be specified to form a search path. +This path will override the default system include path, +.Pa /usr/share/mk . +The system include path will always be appended to the search path used +for "..."-style inclusions and makefile searches (see the +.Fl I +option). +.It Fl n +Display the commands that would have been executed, but do not actually +execute them. +.It Fl P +Collate the output of a given job and display it only when the job finishes, +instead of mixing the output of parallel jobs together. +This option has no effect unless +.Fl j +is used too. +.It Fl p +Only print the input graph, not executing any commands. +The output is the same as +.Fl d Ar g1 . +When combined with +.Fl f Pa /dev/null , +only the builtin rules of +.Nm +are displayed. +.It Fl Q +Do not generate metadata files during build. +Do not use this option if you plan to do an update build later. +.It Fl q +Do not execute any commands, but exit 0 if the specified targets are +up-to-date and 1, otherwise. +.It Fl r +Do not process the system makefile. +.It Fl S +Stop processing when an error is encountered. +Default behaviour. +This is needed to negate the +.Fl k +option during recursive builds. +.It Fl s +Echo all commands as they are executed. +This increases the verbosity of the output of +.Nm +which defaults to not echoing commands as they are executed. +.It Fl t +Rather than re-building a target as specified in the makefile, create it +or update its modification time to make it appear up-to-date. +.It Fl V Ar variable +Print +.Nm Ns 's +idea of the value of +.Ar variable , +in the global context. +Do not build any targets. +Multiple instances of this option may be specified; +the variables will be printed one per line, +with a blank line for each null or undefined variable. +.It Fl v +Be extra verbose. +Print any extra information. +.It Fl X +When using the +.Fl V +option to print the values of variables, +do not recursively expand the values. +.It Ar variable Ns No = Ns Ar value +Set the value of the variable +.Ar variable +to +.Ar value . +.It Fl x Ar warning_options +Specify extended warning options. +This option may be specified several times. +A +.Ar warning_option +can be prefixed with +.Dq Li no +in which case the warning is switched off. +The currently available options are: +.Bl -tag -width indent +.It Li dirsyntax +Warn if anything except blanks and comments follows an +.Ic .endif +or +.Ic .else +directive. +.El +.Pp +See also the +.Ic .WARN +special target. +.El +.Pp +There are seven different types of lines in a makefile: file dependency +specifications, shell commands, variable assignments, include statements, +conditional directives, for loops, and comments. +.Pp +In general, lines may be continued from one line to the next by ending +them with a backslash +.Pq Ql \e . +The trailing newline character and initial whitespace on the following +line are compressed into a single space. +.Sh FILE DEPENDENCY SPECIFICATIONS +Dependency lines consist of one or more targets, an operator, and zero +or more sources. +This creates a relationship where the targets +.Dq depend +on the sources +and are usually created from them. +The exact relationship between the target and the source is determined +by the operator that separates them. +The three operators are as follows: +.Bl -tag -width flag +.It Ic \&: +A target is considered out-of-date if its modification time is less than +those of any of its sources. +Sources for a target accumulate over dependency lines when this operator +is used. +The target is removed if +.Nm +is interrupted. +.It Ic \&! +Targets are always re-created, but not until all sources have been +examined and re-created as necessary. +Sources for a target accumulate over dependency lines when this operator +is used. +The target is removed if +.Nm +is interrupted. +.It Ic :: +If no sources are specified, the target is always re-created. +Otherwise, a target is considered out-of-date if any of its sources has +been modified more recently than the target. +Sources for a target do not accumulate over dependency lines when this +operator is used. +The target will not be removed if +.Nm +is interrupted. +.El +.Pp +Targets and sources may contain the shell wildcard expressions +.Ql \&? , +.Ql * , +.Ql [] +and +.Ql {} . +The expressions +.Ql \&? , +.Ql * +and +.Ql [] +may only be used as part of the final +component of the target or source, and must be used to describe existing +files. +The expression +.Ql {} +need not necessarily be used to describe existing files. +Expansion is in directory order, not alphabetically as done in the shell. +.Sh SHELL COMMANDS +Each target may have associated with it a series of shell commands, normally +used to create the target. +Each of the commands in this script +.Em must +be preceded by a tab. +While any target may appear on a dependency line, only one of these +dependencies may be followed by a creation script, unless the +.Sq Ic :: +operator is used. +.Pp +If the first characters of the command line are +.Sq Ic @ , +.Sq Ic \- , +and/or +.Sq Ic + , +the command is treated specially. +A +.Sq Ic @ +causes the command not to be echoed before it is executed. +A +.Sq Ic \- +causes any non-zero exit status of the command line to be ignored. +A +.Sq Ic + +causes the command to be executed even if +.Fl n +is specified on the command line. +.Sh VARIABLE ASSIGNMENTS +Variables in +.Nm +are much like variables in the shell, and, by tradition, +consist of all upper-case letters. +The five operators that can be used to assign values to variables are as +follows: +.Bl -tag -width Ds +.It Ic = +Assign the value to the variable. +Any previous value is overridden. +.It Ic += +Append the value to the current value of the variable. +.It Ic ?= +Assign the value to the variable if it is not already defined. +.It Ic := +Assign with expansion, i.e., expand the value before assigning it +to the variable. +Normally, expansion is not done until the variable is referenced. +.It Ic != +Expand the value and pass it to the shell for execution and assign +the result to the variable. +Any newlines in the result are replaced with spaces. +.El +.Pp +Any whitespace before the assigned +.Ar value +is removed; if the value is being appended, a single space is inserted +between the previous contents of the variable and the appended value. +.Pp +Variables are expanded by surrounding the variable name with either +curly braces +.Pq Ql {} +or parentheses +.Pq Ql () +and preceding it with +a dollar sign +.Pq Ql $ . +If the variable name contains only a single letter, the surrounding +braces or parentheses are not required. +This shorter form is not recommended. +.Pp +Variable substitution occurs at two distinct times, depending on where +the variable is being used. +Variables in dependency lines are expanded as the line is read. +Variables in shell commands are expanded when the shell command is +executed. +.Pp +The four different classes of variables (in order of increasing precedence) +are: +.Bl -tag -width Ds +.It Environment variables +Variables defined as part of +.Nm Ns 's +environment. +.It Global variables +Variables defined in the makefile or in included makefiles. +.It Command line variables +Variables defined as part of the command line and variables +obtained from the +.Ev MAKEFLAGS +environment variable or the +.Ic .MAKEFLAGS +target. +.It Local variables +Variables that are defined specific to a certain target. +.El +.Pp +If the name of an environment variable appears in a makefile +on the left-hand side of an assignment, +a global variable with the same name is created, and the latter +shadows the former as per their relative precedences. +The environment is not changed in this case, and the change +is not exported to programs executed by +.Nm . +However, a command-line variable actually replaces +the environment variable of the same name if the latter exists, +which is visible to child programs. +.Pp +There are seven local variables in +.Nm : +.Bl -tag -width ".ARCHIVE" +.It Va .ALLSRC +The list of all sources for this target; also known as +.Sq Va > . +.It Va .ARCHIVE +The name of the archive file; also known as +.Sq Va \&! . +.It Va .IMPSRC +The name/path of the source from which the target is to be transformed +(the +.Dq implied +source); also known as +.Sq Va < . +.It Va .MEMBER +The name of the archive member; also known as +.Sq Va % . +.It Va .OODATE +The list of sources for this target that were deemed out-of-date; also +known as +.Sq Va \&? . +.It Va .PREFIX +The file prefix of the file, containing only the file portion, no suffix +or preceding directory components; also known as +.Sq Va * . +.It Va .TARGET +The name of the target; also known as +.Sq Va @ . +.El +.Pp +The shorter forms +.Sq Va @ , +.Sq Va \&! , +.Sq Va < , +.Sq Va % , +.Sq Va \&? , +.Sq Va > , +and +.Sq Va * +are permitted for backward +compatibility and are not recommended. +The six variables +.Sq Va @F , +.Sq Va @D , +.Sq Va +.It Ic .include Ar \*qfile\*q +Include the specified makefile. +Variables between the angle brackets +or double quotes are expanded to form the file name. +If angle brackets +are used, the included makefile is expected to be in the system +makefile directory. +If double quotes are used, the including +makefile's directory and any directories specified using the +.Fl I +option are searched before the system +makefile directory. +.It Ic .sinclude Ar +.It Ic .sinclude Ar \*qfile\*q +Like +.Ic .include , +but silently ignored if the file cannot be found and opened. +.It Ic .undef Ar variable +Un-define the specified global variable. +Only global variables may be un-defined. +.It Ic .error Ar message +Terminate processing of the makefile immediately. +The filename of the +makefile, the line on which the error was encountered and the specified +message are printed to the standard error output and +.Nm +terminates with exit code 1. +Variables in the message are expanded. *** DIFF OUTPUT TRUNCATED AT 1000 LINES ***