Add makeenv.1 and README

Signed-off-by: Mattias Andrée <maandree@kth.se>

3 files changed, 479 insertions, 2 deletions

diff --git a/README b/README
new file mode 100644
index 0000000..1739185
--- /dev/null
+++ b/README
@@ -0,0 +1,191 @@
+NAME
+	makeenv - Run make(1) with environment loaded from .makeenv
+
+SYNPOSIS
+	makeenv [arguments] ...
+
+DESCRIPTION
+	The makeenv utility opens the file .makeenv if it exists in the
+	current working directory and scans it for options, macros, and
+	targets to specify along with the provided arguments when it
+	executes make(1). Any macro listed in .makeenv is also put in
+	the environment.
+
+	After loading .makeenv and adding populating the environment,
+	makeenv will inspect it's environment, makeenv itself is
+	affected by the environment variables, which also are make(1)
+	macros; this if you need a specific implementation of make(1)
+	for a project, it can be specified in the .makeenv file.
+
+	When executng make(1), makeenv may reorder the arguments, and
+	will put any option listed in .makeenv at the beginning, any
+	macro listed in .makeenv before the macros in the arguments,
+	and any target listed in .makeenv before the targets in the
+	arguments.
+
+	makeenv is designed to be usable in place of make(1), that is,
+	the user can create add the alias makeenv=make in his shell,
+	without any adverse affect. makeenv will pass on it's arguments
+	as is to make(1) (or whichever utility is specified in the
+	environment variable MAKEENV_MAKE or the environment variable
+	MAKE) without validation or modifications, if the .makeenv does
+	not exist.
+
+OPTIONS
+	The makeenv utility passes it's options to the make(1) utility
+	and do not act on any of the it self, however in order to
+	properly interleave options and operands specified in the
+	.makeenv file, it have to understand which options take an
+	argument and which do not. By default, the makeenv utility only
+	understands the options specified by POSIX, and the argumented
+	option -W (vendor options), as well as long options that start
+	with two dashes (--) provided that the same command line
+	argument contains an equals sign (=). The user can modify the
+	environment variables to modify how the makeenv utility
+	understands the options. See the section ENVIRONMENT VARIABLES
+	for more information. The current version only support options
+	that consist of a dash (-) followed by any other character and
+	options that start with two dashes (--), followed by at least
+	one character, but may not contain an equals sign (=), as these
+	are treated as delimiters between long options and their
+	associated argument.
+
+STDIN
+	Not used.
+
+INPUT FILES
+	None.
+
+ENVIRONMENT VARIABLES
+	The following environment variables affect the execution of
+	makeenv:
+
+	PATH
+		Default.
+
+	MAKEENV_MAKE, MAKE
+		The command that shall be invoked by the utility. The
+		environment variable MAKEENV_MAKE has precedence over
+		MAKE; MAKE is only used if MAKEENV_MAKE is not defined.
+		If neither is defined, the default value make is used.
+
+	MAKEENV_OPTS_NO_ARG
+		List of options that makeenv shall interpret as make(1)
+		options that do not have any argument. (Default is
+		eiknpqrSst, meaning the options -e, -i, -k, -n, -p, -q,
+		-r, -S, -s, and -t.)
+
+	MAKEENV_OPTS_ARG
+		List of options that makeenv shall interpret as make(1)
+		options that have an argument. (Default is fW, meaning
+		the options -f and -W.)
+
+	MAKEENV_OPTS_OPT_ATTACHED_ARG
+		List of options that makeenv shall interpret as make(1)
+		options that have an argument only if there are
+		additional characters after the option character in the
+		same command line argument. (Default is the empty
+		string, meaning no options.)
+
+	MAKEENV_OPTS_OPT_ARG
+		List of options that makeenv shall interpret as make(1)
+		options that have an argument if there are additional
+		characters after the option character in the same
+		command line argument or if argument is followed
+		directly by another argument which does not start with
+		a dash (-). (Default is the empty string, meaning no
+		options.)
+
+	MAKEENV_LONG_OPTS_NO_ARG
+		List of options that makeenv shall interpret as make(1)
+		options that do not have any argument. (Default is
+		eiknpqrSst, meaning the options -e, -i, -k, -n, -p, -q,
+		-r, -S, -s, and -t.)
+
+	MAKEENV_OPTS_ARG
+		List of options that makeenv shall interpret as make(1)
+		options that have an argument. (Default is fW, meaning
+		the options -f and -W.)
+
+	MAKEENV_OPTS_OPT_ATTACHED_ARG
+		List of options that makeenv shall interpret as make(1)
+		options that have an argument only if there are
+		additional characters after the option character in
+		the same command line argument. (Default is the empty
+		string, meaning no options.)
+
+	MAKEENV_OPTS_OPT_ARG
+		List of options that makeenv shall interpret as make(1)
+		options that have an argument if there are additional
+		characters after the option character in the same
+		command line argument or if argument is followed
+		directly by another argument which does not start with
+		a dash (-). (Default is the empty string, meaning no
+		options.)
+
+	MAKEENV_LONG_OPTS_NO_ARG
+		Space-separated list of long options that makeenv shall
+		interpret as make(1) options that do not have any
+		argument unless it is followed directly by an equals
+		sign (=) in the same command line argument. Options
+		that do not start with two dashes (--) are silently
+		ignored. (Default is the empty string, meaning no
+		options.)
+
+	MAKEENV_LONG_OPTS_ARG
+		Space-separated list of long options that makeenv shall
+		interpret as make(1) options that have an argument that
+		must either be specified in the next command line
+		argument or after an equals sign (=) the shall directly
+		follow the option string in the same command line
+		argument. Options that do not start with two dashes
+		(--) are silently ignored. (Default is the empty string,
+		meaning no options.)
+
+	MAKEENV_LONG_OPTS_OPT_ARG
+		Space-separated list of long options that makeenv shall
+		interpret as make(1) options that have an argument if
+		it is the option string is is directly followed by
+		equals sign (=) in the same command line argument or if
+		argument is followed directly by another argument which
+		does not start with a dash (-). Options that do not
+		start with two dashes (--) are silently ignored.
+		(Default is the empty string, meaning no options.)
+
+	Any macro listed in .makeenv is loaded into the environment
+	before the utility inspects the environement.
+
+ASYNCHRONOUS EVENTS
+	Default.
+
+STDOUT
+	Not used.
+
+STDERR
+	The standard error is used only for diagnostic messages.
+
+OUTPUT FILES
+	None.
+
+EXTENDED DESCRIPTION
+	None.
+
+EXIT STATUS
+	If the make(1) utility is invoked, the exit status of makeenv
+	is the exit status of the make(1); utility otherwise, the
+	makeenv utility exits with one of the following values:
+
+	125	An error occurred in the makeenv utility.
+
+	126	The make(1) utility was found but could not be invoked.
+
+	127	The make(1) utility could not be found.
+
+CONSEQUENCES OF ERRORS
+	Default.
+
+FUTURE DIRECTIONS
+	None.
+
+SEE ALSO
+	makeenv(5), make(1)
diff --git a/TODO b/TODO
index 9b957b4..2d831b7 100644
--- a/TODO
+++ b/TODO
@@ -1,6 +1,4 @@
-Write makeenv.1
 Write makeenv.5
-Write README
 
 Bugs:
 	Options in MAKEENV_OPTS_OPT_ARG and MAKEENV_LONG_OPTS_OPT_ARG can
diff --git a/makeenv.1 b/makeenv.1
new file mode 100644
index 0000000..61481e6
--- /dev/null
+++ b/makeenv.1
@@ -0,0 +1,288 @@
+.TH MAKEENV 1 MAKEENV
+.SH NAME
+makeenv - Run make(1) with environment loaded from .makeenv
+.SH SYNPOSIS
+.B makeenv
+.RI [ arguments "] ..."
+.SH DESCRIPTION
+The
+.B makeenv
+utility opens the file
+.I .makeenv
+if it exists in the current working directory and scans it
+for options, macros, and targets to specify along with the
+provided
+.I arguments
+when it executes
+.BR make (1).
+Any macro listed in
+.I .makeenv
+is also put in the environment.
+.PP
+After loading
+.I .makeenv
+and adding populating the environment,
+.B makeenv
+will inspect it's environment,
+.B makeenv
+itself is affected by the environment variables, which
+also are
+.BR make (1)
+macros; this if you need a specific implementation of
+.BR make (1)
+for a project, it can be specified in the
+.I .makeenv
+file.
+.PP
+When executng
+.BR make (1),
+.B makeenv
+may reorder the
+.IR arguments ,
+and will put any option listed in
+.I .makeenv
+at the beginning, any macro listed in
+.I .makeenv
+before the macros in the
+.IR arguments ,
+and any target  listed in
+.I .makeenv
+before the targets in the
+.IR arguments .
+.PP
+.B makeenv
+is designed to be usable in place of
+.BR make (1),
+that is, the user can create add the
+.B alias
+.I makeenv=make
+in his shell, without any adverse affect.
+.B makeenv
+will pass on it's arguments as is to
+.BR make (1)
+(or whichever utility is specified in the environment
+variable
+.I MAKEENV_MAKE
+or the environment variable
+.IR MAKE )
+without validation or modifications, if the
+.B .makeenv
+does not exist.
+.SH OPTIONS
+The
+.BR makeenv
+utility passes it's options to the
+.BR make (1)
+utility and do not act on any of the it self, however
+in order to properly interleave options and operands
+specified in the
+.I .makeenv
+file, it have to understand which options take an argument
+and which do not. By default, the
+.BR makeenv
+utility only understands the options specified by POSIX,
+and the argumented option
+.B -W
+(vendor options), as well as long options that start with
+two dashes
+.RB (--)
+provided that the same command line argument contains an
+equals sign
+.RB ( = ).
+The user can modify the environment
+variables to modify how the
+.BR makeenv
+utility understands the options. See the section
+.B ENVIRONMENT VARIABLES
+for more information. The current version only support
+options that consist of a dash
+.RB ( - )
+followed by any other character and options that start
+with two dashes
+.RB ( -- ),
+followed by at least one character, but may not contain
+an equals sign
+.RB ( = ),
+as these are treated as delimiters between long options
+and their associated argument.
+.BR 
+.SH STDIN
+Not used.
+.SH INPUT FILES
+None.
+.SH ENVIRONMENT VARIABLES
+The following environment variables affect the execution of
+.BR makeenv :
+.TP
+.I PATH
+Default.
+.TP
+.IR MAKEENV_MAKE ", " MAKE
+The command that shall be invoked by the utility.
+The environment variable
+.I MAKEENV_MAKE
+has precedence over
+.IR MAKE;
+.I MAKE
+is only used if
+.I MAKEENV_MAKE
+is not defined. If neither is defined, the default value
+.B make
+is used.
+.TP
+.I MAKEENV_OPTS_NO_ARG
+List of options that
+.B makeenv
+shall interpret as
+.BR make (1)
+options that do not have any argument.
+(Default is
+.BR eiknpqrSst ,
+meaning the options
+.BR -e ,
+.BR -i ,
+.BR -k ,
+.BR -n ,
+.BR -p ,
+.BR -q ,
+.BR -r ,
+.BR -S ,
+.BR -s ,
+and
+.BR -t .)
+.TP
+.I MAKEENV_OPTS_ARG
+List of options that
+.B makeenv
+shall interpret as
+.BR make (1)
+options that have an argument.
+(Default is
+.BR fW ,
+meaning the options
+.B -f
+and
+.BR -W .)
+.TP
+.I MAKEENV_OPTS_OPT_ATTACHED_ARG
+List of options that
+.B makeenv
+shall interpret as
+.BR make (1)
+options that have an argument only if
+there are additional characters after
+the option character in the same
+command line argument. (Default is
+the empty string, meaning no options.)
+.TP
+.I MAKEENV_OPTS_OPT_ARG
+List of options that
+.B makeenv
+shall interpret as
+.BR make (1)
+options that have an argument if there
+are additional characters after
+the option character in the same
+command line argument or if argument is
+followed directly by another argument
+which does not start with a dash
+.RB ( - ).
+(Default is
+the empty string, meaning no options.)
+.TP
+.I MAKEENV_LONG_OPTS_NO_ARG
+Space-separated list of long options that
+.B makeenv
+shall interpret as
+.BR make (1)
+options that do not have any argument
+unless it is followed directly by an
+equals sign
+.RB ( = )
+in the same command line argument.
+Options that do not start with two dashes
+.RB ( -- )
+are silently ignored. (Default is the
+empty string, meaning no options.)
+.TP
+.I MAKEENV_LONG_OPTS_ARG
+Space-separated list of long options that
+.B makeenv
+shall interpret as
+.BR make (1)
+options that have an argument that must
+either be specified in the next command
+line argument or after an
+equals sign
+.RB ( = )
+the shall directly follow the option
+string in the same command line argument.
+Options that do not start with two dashes
+.RB ( -- )
+are silently ignored. (Default is the
+empty string, meaning no options.)
+.TP
+.I MAKEENV_LONG_OPTS_OPT_ARG
+Space-separated list of long options that
+.B makeenv
+shall interpret as
+.BR make (1)
+options that have an argument if it is
+the option string is is directly followed
+by equals sign
+.RB ( = )
+in the same command line argument or if
+argument is followed directly by another
+argument which does not start with a dash
+.RB ( - ).
+Options that do not start with two dashes
+.RB ( -- )
+are silently ignored. (Default is the
+empty string, meaning no options.)
+.PP
+Any macro listed in
+.I .makeenv
+is loaded into the environment before the utility inspects
+the environement.
+.SH ASYNCHRONOUS EVENTS
+Default.
+.SH STDOUT
+Not used.
+.SH STDERR
+The standard error is used only for diagnostic messages.
+.SH OUTPUT FILES
+None.
+.SH EXTENDED DESCRIPTION
+None.
+.SH EXIT STATUS
+If the
+.BR make (1)
+utility is invoked, the exit status of
+.B makeenv
+is the exit status of the
+.BR make (1);
+utility otherwise, the
+.B makeenv
+utility exits with one of the following values:
+.TP
+125
+An error occurred in the
+.B makeenv
+utility.
+.TP
+126
+The
+.BR make (1)
+utility was found but could not be invoked.
+.TP
+127
+The
+.BR make (1)
+utility could not be found.
+.SH CONSEQUENCES OF ERRORS
+Default.
+.SH FUTURE DIRECTIONS
+None.
+.SH SEE ALSO
+.BR makeenv (5),
+.BR make (1)