From 17355df322ddb858362fd8a1a889e73a14c2b3cc Mon Sep 17 00:00:00 2001 From: Mattias Andrée Date: Sun, 11 Feb 2024 22:28:27 +0100 Subject: Add makeenv.1 and README MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Mattias Andrée --- README | 191 +++++++++++++++++++++++++++++++++++++++++ TODO | 2 - makeenv.1 | 288 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 3 files changed, 479 insertions(+), 2 deletions(-) create mode 100644 README create mode 100644 makeenv.1 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) -- cgit v1.2.3-70-g09d2