diff --git a/README b/README --- a/README +++ b/README @@ -1,4 +1,5 @@ SYNOPSIS + arx (-h | -[?] | --help) arx (-v | --version) arx shdat (-b )? (-o )? < input @@ -6,144 +7,146 @@ arx tmpx * (//+ (//+ *)?)? DESCRIPTION - A UNIX executable is a simple thing -- a file the kernel can execute, - one way or another, via an interpreter or directly as object code. - Every executable induces a family of executions -- instances of execu- - tion with different command line arguments, with different files in the - working directory and with different environment variables present. + A UNIX executable is a simple thing -- a file the kernel can execute, + one way or another, via an interpreter or directly as object code. + Every executable induces a family of executions -- instances of + execution with different command line arguments, with different files + in the working directory and with different environment variables + present. - The arx tool captures the parameters of an execution and encodes them - as an executable, making for easy, consistent transfer and repetition - of a particular run. The generated executable ensures that each run - occurs in a freshly allocated temporary directory, with only the - desired files in scope; it uses traps to ensure the cleanup of this - directory; and its format is a simple POSIX shell script, relying on + The arx tool captures the parameters of an execution and encodes them + as an executable, making for easy, consistent transfer and repetition + of a particular run. The generated executable ensures that each run + occurs in a freshly allocated temporary directory, with only the + desired files in scope; it uses traps to ensure the cleanup of this + directory; and its format is a simple POSIX shell script, relying on just a few shell tools. DEPENDENCIES - The arx tool relies on the presence of sed, tr, date, head, tar, hex- - dump and sh. When unpacking tar archives, it may use the -j or -z + The arx tool relies on the presence of sed, tr, date, head, tar, + hexdump and sh. When unpacking tar archives, it may use the -j or -z (bzip2 and gzip, respectively) options of tar. Scripts have been tested - with dash and the GNU tools as well as the sh implementation and user- - land tools that are part of busybox. + with dash and the GNU tools as well as the sh implementation and + userland tools that are part of busybox. APPLICATION - The tmpx subcommand of arx offers a variety of options for bundling - code and a task to run. The shdat subcommand exposes the lower-level - functionality of encoding binary data in a shell script that outputs - that binary data, using HERE documents and some odd replacement rules + The tmpx subcommand of arx offers a variety of options for bundling + code and a task to run. The shdat subcommand exposes the lower-level + functionality of encoding binary data in a shell script that outputs + that binary data, using HERE documents and some odd replacement rules for nulls. - Scripts generated by tmpx and shdat may be fed to sh over STDIN to exe- - cute them. This can be helpful when using ssh and sudo to set up an + Scripts generated by tmpx and shdat may be fed to sh over STDIN to + execute them. This can be helpful when using ssh and sudo to set up an execution context; for example: arx tmpx ... | ssh user@host.com sudo sh - Scripts generated by tmpx will pass their arguments to the contained + Scripts generated by tmpx will pass their arguments to the contained script or command. To pass arguments when piping to sh, use -s: arx tmpx ... | ssh user@host.com sudo sh -s a b c - Some arguments to the generated script will be treated specially, - namely, --extract, --no-rm and --no-run. Please see the section on + Some arguments to the generated script will be treated specially, + namely, --extract, --no-rm and --no-run. Please see the section on Passing Arguments, below, for more information about these options. ARX COMMANDLINE PROCESSING - For all subcommands, when options overlap in their effect -- for exam- - ple, setting the output with -o -- the rightmost option takes prece- - dence. Whenever -h, -? or --help is present on the command line, help - is displayed and the program exits. + For all subcommands, when options overlap in their effect -- for + example, setting the output with -o -- the rightmost option takes + precedence. Whenever -h, -? or --help is present on the command line, + help is displayed and the program exits. - When paths are specified on an arx command line, they must be quali- - fied, starting with /, ./ or ../. This simplifies the command line syn- - tax, overall, without introducing troublesome ambiguities. + When paths are specified on an arx command line, they must be + qualified, starting with /, ./ or ../. This simplifies the command line + syntax, overall, without introducing troublesome ambiguities. TMPX The tmpx subcommand bundles together archives, environment settings and - an executable or shell command in to a Bourne-compatible script that - runs the command or executable in a temporary directory, after having + an executable or shell command in to a Bourne-compatible script that + runs the command or executable in a temporary directory, after having unpacked the archives and set the environment. - Any number of file path arguments may be specified; they will be inter- - preted as tar archives to include in bundled script. If - is given, - then STDIN will be included as an archive stream. If no arguments are - given, it is assumed that no archives are desired and only the command - and environment are bundled. + Any number of file path arguments may be specified; they will be + interpreted as tar archives to include in bundled script. If - is + given, then STDIN will be included as an archive stream. If no + arguments are given, it is assumed that no archives are desired and + only the command and environment are bundled. - The temporary directory created by the script is different for each - invocation, with a name of the form /tmp/tmpx--. - The timestamp format is %Y.%m.%dT%H.%M.%SZ, in UTC. One happy conse- - quence of this is that earlier jobs sort ASCIIbetically before later - jobs. After execution, the temporary directory is removed (or not, - depending on the -rm[10!_] family of options). + The temporary directory created by the script is different for each + invocation, with a name of the form /tmp/tmpx--. + The timestamp format is %Y.%m.%dT%H.%M.%SZ, in UTC. One happy + consequence of this is that earlier jobs sort ASCIIbetically before + later jobs. After execution, the temporary directory is removed (or + not, depending on the -rm[10!_] family of options). -rm0, -rm1, -rm_, -rm! - By default, the temporary directory created by the script + By default, the temporary directory created by the script will be deleted no matter the exit status status of the task. These options cause a script to be generated that deletes the - temporary directory only on success, only on failure, always + temporary directory only on success, only on failure, always (the default) or never. --shared - Causes the temporary directory to be identified by a hash of - the ARX archive, instead of by date and time. Different runs - of the same archive will share the same directory. Note that + Causes the temporary directory to be identified by a hash of + the ARX archive, instead of by date and time. Different runs + of the same archive will share the same directory. Note that this implies shared state and every disadvantage thereof. -b - Please see the documentation for this option, shared with + Please see the documentation for this option, shared with shdat, below. -o - By default, the generated script is sent to STDOUT. With -o, + By default, the generated script is sent to STDOUT. With -o, output is redirected to the given path. -e - Causes the file specified to be packaged as the task to be - run. A binary executable, a Ruby script or a longish shell + Causes the file specified to be packaged as the task to be + run. A binary executable, a Ruby script or a longish shell script all fit here. - In addition to these options, arguments of the form VAR=VALUE are rec- - ognized as environment mappings and stored away in the script, to be + In addition to these options, arguments of the form VAR=VALUE are + recognized as environment mappings and stored away in the script, to be sourced on execution. - Without -e, the tmpx subcommand tries to find the task to be run as a - sequence of arguments delimited by a run of slashes. The following + Without -e, the tmpx subcommand tries to find the task to be run as a + sequence of arguments delimited by a run of slashes. The following forms are all recognized: arx tmpx ...some args... // ...command... arx tmpx ...some args... // ...command... // ...more args... arx tmpx // ...command... // ...some args... - The slash runs must have the same number of slashes and must be the - longest continuous runs of slashes on the command line. The command + The slash runs must have the same number of slashes and must be the + longest continuous runs of slashes on the command line. The command will be included as-is in a Bourne shell script. SHDAT - The shdat subcommand translates binary data in to a shell script which - outputs the binary data. The data is encoded in HERE documents in such - a way that data without NULs is not changed and that data with NULs is - minimally expanded: about 1% for randomish data like compressed tar- - balls and about 10% in pathological cases. + The shdat subcommand translates binary data in to a shell script which + outputs the binary data. The data is encoded in HERE documents in such + a way that data without NULs is not changed and that data with NULs is + minimally expanded: about 1% for randomish data like compressed + tarballs and about 10% in pathological cases. - The shdat subcommand can be given any number of paths, which will be + The shdat subcommand can be given any number of paths, which will be concatenated in the order given. If no path is given, or if - is given, then STDIN will be read. -b - The size of data chunks to place in each HERE document. The - argument is a positive integer followed by suffixes like B, - K, KiB, M and MiB, in the manner of dd, head and many other - tools. The default is 4MiB. This is unlikely to make a dif- - ference for you unless the generated script is intended to be - run on a memory-constrained system. + The size of data chunks to place in each HERE document. The + argument is a positive integer followed by suffixes like B, + K, KiB, M and MiB, in the manner of dd, head and many other + tools. The default is 4MiB. This is unlikely to make a + difference for you unless the generated script is intended to + be run on a memory-constrained system. -o - By default, the generated script is sent to STDOUT. With -o, + By default, the generated script is sent to STDOUT. With -o, output is redirected to the given path. EXAMPLES + # Installer script that preserves failed builds. git archive HEAD | bzip2 | arx tmpx -rm0 - // make install > go.sh # Now install as root; but don't log in as root. @@ -164,22 +167,22 @@ PASSING ARGUMENTS TO GENERATED SCRIPTS The scripts generated by tmpx treat some arguments as special, internal - options, to allow for inspecting them should there be a need to deter- - mine their contents. + options, to allow for inspecting them should there be a need to + determine their contents. --extract Unpack the data in the present directory and do nothing else. --no-rm - Run the script as normal but do not delete the generated tem- - porary directory. + Run the script as normal but do not delete the generated + temporary directory. --no-run - Unpack into a temporary directory as normal but do not run + Unpack into a temporary directory as normal but do not run the user's command. - To prevent arguments from being specially treated, use // in the argu- - ment list: + To prevent arguments from being specially treated, use // in the + argument list: a-tmpx-script.sh --no-rm // a b c --extract @@ -190,16 +193,16 @@ arx tmpx // printf "'%s\n'" '"$@"' | sh -s // ab c --no-rm NOTES - The timestamp is not the common ISO 8601 format, %Y-%m-%dT%H:%M:%SZ, - because of software and build processes that attach special meaning to + The timestamp is not the common ISO 8601 format, %Y-%m-%dT%H:%M:%SZ, + because of software and build processes that attach special meaning to colons in pathnames. BUGS - The command line parser offers no hints or help of any kind; it fails - with the simple message "argument error". The two most common mistakes + The command line parser offers no hints or help of any kind; it fails + with the simple message "argument error". The two most common mistakes I make are: - o Not qualifying paths with /, ./ or ../. + • Not qualifying paths with /, ./ or ../. - o Not specifying a subcommand (tmpx or shdat). + • Not specifying a subcommand (tmpx or shdat). diff --git a/System/Posix/ARX.hs b/System/Posix/ARX.hs --- a/System/Posix/ARX.hs +++ b/System/Posix/ARX.hs @@ -10,4 +10,3 @@ import System.Posix.ARX.Programs import System.Posix.ARX.Sh import System.Posix.ARX.Tar - diff --git a/System/Posix/ARX/CLI.hs b/System/Posix/ARX/CLI.hs --- a/System/Posix/ARX/CLI.hs +++ b/System/Posix/ARX/CLI.hs @@ -181,4 +181,3 @@ | otherwise = Char8.hPutStr stderr (b `Char8.snoc` '\n') die msg = err msg >> exitFailure - diff --git a/System/Posix/ARX/CLI/CLTokens.hs b/System/Posix/ARX/CLI/CLTokens.hs --- a/System/Posix/ARX/CLI/CLTokens.hs +++ b/System/Posix/ARX/CLI/CLTokens.hs @@ -188,4 +188,3 @@ -} sizeBounded :: forall b . (Bounded b, Integral b) => Parser b sizeBounded = fromInteger . min (toInteger (maxBound :: b)) <$> size - diff --git a/System/Posix/ARX/CLI/Options.hs b/System/Posix/ARX/CLI/Options.hs --- a/System/Posix/ARX/CLI/Options.hs +++ b/System/Posix/ARX/CLI/Options.hs @@ -174,4 +174,3 @@ classify = Just <$> satisfy slashRun <|> Nothing <$ anyArg longestFirst = sortBy (comparing (negate . Bytes.length)) slashRun s = Char8.all (== '/') s && Bytes.length s > 1 - diff --git a/System/Posix/ARX/HEREDat.hs b/System/Posix/ARX/HEREDat.hs --- a/System/Posix/ARX/HEREDat.hs +++ b/System/Posix/ARX/HEREDat.hs @@ -24,7 +24,6 @@ import qualified Blaze.ByteString.Builder as Blaze import qualified Blaze.ByteString.Builder.Char8 as Blaze -import qualified Data.ByteString.Nums.Careless as Bytes {-| A chunk describes a block of binary data ready for inclusion in a shell @@ -205,7 +204,7 @@ encoded (SafeChunk _) = False encoded (EncodedChunk _ _ _ _) = True -{-| +{-| -} script block = mconcat $ case block of SafeChunk bytes -> [script (chunk bytes)] -- Convert to Encoded @@ -242,4 +241,3 @@ - more compact than base 64; but whether shell decoders can effectively - realize this efficiency is another matter. -} - diff --git a/System/Posix/ARX/Programs.hs b/System/Posix/ARX/Programs.hs --- a/System/Posix/ARX/Programs.hs +++ b/System/Posix/ARX/Programs.hs @@ -41,7 +41,7 @@ ("", "") -> [] (a , "") -> [chunkIt a] (a , b) -> chunkIt a : chunked b - where + where chunkIt = script . chunk . mconcat . LazyB.toChunks @@ -78,5 +78,3 @@ [ ] -> "" shdat = interpret encoder unblz = Blaze.toLazyByteString - - diff --git a/System/Posix/ARX/Sh.hs b/System/Posix/ARX/Sh.hs --- a/System/Posix/ARX/Sh.hs +++ b/System/Posix/ARX/Sh.hs @@ -66,4 +66,3 @@ class Raw t where raw :: t -> ByteString - diff --git a/System/Posix/ARX/TMPXTools.hs b/System/Posix/ARX/TMPXTools.hs --- a/System/Posix/ARX/TMPXTools.hs +++ b/System/Posix/ARX/TMPXTools.hs @@ -79,4 +79,3 @@ isHole :: ByteString -> Bool isHole line = "# To be set by tool." `Bytes.isSuffixOf` line - diff --git a/arx.cabal b/arx.cabal --- a/arx.cabal +++ b/arx.cabal @@ -1,7 +1,8 @@ +cabal-version : 3.0 name : arx -version : 0.3.2 +version : 0.3.3 category : Text -license : BSD3 +license : BSD-3-Clause license-file : LICENSE author : Jason Dusek maintainer : oss@solidsnack.be @@ -46,7 +47,6 @@ For each supported platform, there is an archive containing @arx@ and signature files (SHA 512 and GPG). -cabal-version : >= 1.6 build-type : Simple extra-source-files : README , LICENSE @@ -66,18 +66,17 @@ library - build-depends : base >= 2 && <= 5 - , bytestring >= 0.9 - , containers - , attoparsec >= 0.9.1.2 - , blaze-builder >= 0.3 - , bytestring-nums >= 0.3.3 - , file-embed >= 0.0.4.1 - , parsec >= 3.1.2 - , process >= 1.0 - , shell-escape >= 0.1.1 - , template-haskell - , hashable + build-depends : base >= 2 && < 5 + , bytestring >= 0.9 && < 1 + , containers >= 0.6 && < 1 + , attoparsec >= 0.9.1.2 && < 1 + , blaze-builder >= 0.3 && < 1 + , file-embed >= 0.0.4.1 && < 1 + , parsec >= 3.1.2 && < 4 + , process >= 1.0 && < 2 + , shell-escape >= 0.1.1 && < 2 + , template-haskell >= 1 && < 3 + , hashable >= 1 && < 2 exposed-modules : System.Posix.ARX System.Posix.ARX.CLI System.Posix.ARX.CLI.CLTokens @@ -87,7 +86,8 @@ System.Posix.ARX.Sh System.Posix.ARX.TMPXTools System.Posix.ARX.Tar - extensions : FlexibleInstances + default-language : Haskell2010 + default-extensions : FlexibleInstances FunctionalDependencies MultiParamTypeClasses OverloadedStrings @@ -101,19 +101,19 @@ buildable : False else buildable : True - build-depends : base >= 2 && <= 5 - , bytestring >= 0.9 - , containers - , attoparsec >= 0.9.1.2 - , blaze-builder >= 0.3 - , bytestring-nums >= 0.3.3 - , file-embed >= 0.0.4.1 - , parsec >= 3.1.2 - , process >= 1.0 - , shell-escape >= 0.1.1 - , template-haskell - , hashable - extensions : FlexibleInstances + build-depends : base >= 2 && < 5 + , bytestring >= 0.9 && < 1 + , containers >= 0.6 && < 1 + , attoparsec >= 0.9.1.2 && < 1 + , blaze-builder >= 0.3 && < 1 + , file-embed >= 0.0.4.1 && < 1 + , parsec >= 3.1.2 && < 4 + , process >= 1.0 && < 2 + , shell-escape >= 0.1.1 && < 2 + , template-haskell >= 1 && < 3 + , hashable >= 1 && < 2 + default-language : Haskell2010 + default-extensions : FlexibleInstances FunctionalDependencies MultiParamTypeClasses OverloadedStrings diff --git a/docs/blessed/arx.man b/docs/blessed/arx.man --- a/docs/blessed/arx.man +++ b/docs/blessed/arx.man @@ -1,8 +1,5 @@ .\" Man page generated from reStructuredText. . -.TH "ARX" "1" "%F" "0.2.2" "arx" -.SH NAME -arx \- archived execution . .nr rst2man-indent-level 0 . @@ -30,19 +27,20 @@ .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. +.TH "ARX" "1" "%F" "0.3.3" "arx" +.SH NAME +arx \- archived execution .SH SYNOPSIS .INDENT 0.0 .INDENT 3.5 .sp -.nf -.ft C +.EX arx (\-h | \-[?] | \-\-help) arx (\-v | \-\-version) arx shdat (\-b )? (\-o )? < input arx shdat (\-b )? (\-o )? + arx tmpx * (//+ (//+ *)?)? -.ft P -.fi +.EE .UNINDENT .UNINDENT .SH DESCRIPTION @@ -79,11 +77,9 @@ .INDENT 0.0 .INDENT 3.5 .sp -.nf -.ft C +.EX arx tmpx ... | ssh user@host.com sudo sh -.ft P -.fi +.EE .UNINDENT .UNINDENT .sp @@ -92,11 +88,9 @@ .INDENT 0.0 .INDENT 3.5 .sp -.nf -.ft C +.EX arx tmpx ... | ssh user@host.com sudo sh \-s a b c -.ft P -.fi +.EE .UNINDENT .UNINDENT .sp @@ -172,13 +166,11 @@ .INDENT 0.0 .INDENT 3.5 .sp -.nf -.ft C +.EX arx tmpx ...some args... // ...command... arx tmpx ...some args... // ...command... // ...more args... arx tmpx // ...command... // ...some args... -.ft P -.fi +.EE .UNINDENT .UNINDENT .sp @@ -217,8 +209,7 @@ .INDENT 0.0 .INDENT 3.5 .sp -.nf -.ft C +.EX # Installer script that preserves failed builds. git archive HEAD | bzip2 | arx tmpx \-rm0 \- // make install > go.sh # Now install as root; but don\(aqt log in as root. @@ -236,8 +227,7 @@ # Test out Cabal source distribution of this package: arx tmpx // \(aqcd arx\-* && cabal configure && cabal build\(aq // \e \-rm0 ./dist/arx\-0.0.0.tar.gz | sh -.ft P -.fi +.EE .UNINDENT .UNINDENT .SH PASSING ARGUMENTS TO GENERATED SCRIPTS @@ -268,11 +258,9 @@ .INDENT 0.0 .INDENT 3.5 .sp -.nf -.ft C +.EX a\-tmpx\-script.sh \-\-no\-rm // a b c \-\-extract -.ft P -.fi +.EE .UNINDENT .UNINDENT .sp @@ -282,11 +270,9 @@ .INDENT 0.0 .INDENT 3.5 .sp -.nf -.ft C -arx tmpx // printf "\(aq%s\en\(aq" \(aq"$@"\(aq | sh \-s // ab c \-\-no\-rm -.ft P -.fi +.EX +arx tmpx // printf \(dq\(aq%s\en\(aq\(dq \(aq\(dq$@\(dq\(aq | sh \-s // ab c \-\-no\-rm +.EE .UNINDENT .UNINDENT .SH NOTES @@ -297,7 +283,7 @@ .SH BUGS .sp The command line parser offers no hints or help of any kind; it fails with the -simple message "argument error". The two most common mistakes I make are: +simple message \(dqargument error\(dq. The two most common mistakes I make are: .INDENT 0.0 .IP \(bu 2 Not qualifying paths with \fB/\fP, \fB\&./\fP or \fB\&../\fP\&. diff --git a/docs/blessed/arx.txt b/docs/blessed/arx.txt --- a/docs/blessed/arx.txt +++ b/docs/blessed/arx.txt @@ -1,4 +1,5 @@ SYNOPSIS + arx (-h | -[?] | --help) arx (-v | --version) arx shdat (-b )? (-o )? < input @@ -6,144 +7,146 @@ arx tmpx * (//+ (//+ *)?)? DESCRIPTION - A UNIX executable is a simple thing -- a file the kernel can execute, - one way or another, via an interpreter or directly as object code. - Every executable induces a family of executions -- instances of execu- - tion with different command line arguments, with different files in the - working directory and with different environment variables present. + A UNIX executable is a simple thing -- a file the kernel can execute, + one way or another, via an interpreter or directly as object code. + Every executable induces a family of executions -- instances of + execution with different command line arguments, with different files + in the working directory and with different environment variables + present. - The arx tool captures the parameters of an execution and encodes them - as an executable, making for easy, consistent transfer and repetition - of a particular run. The generated executable ensures that each run - occurs in a freshly allocated temporary directory, with only the - desired files in scope; it uses traps to ensure the cleanup of this - directory; and its format is a simple POSIX shell script, relying on + The arx tool captures the parameters of an execution and encodes them + as an executable, making for easy, consistent transfer and repetition + of a particular run. The generated executable ensures that each run + occurs in a freshly allocated temporary directory, with only the + desired files in scope; it uses traps to ensure the cleanup of this + directory; and its format is a simple POSIX shell script, relying on just a few shell tools. DEPENDENCIES - The arx tool relies on the presence of sed, tr, date, head, tar, hex- - dump and sh. When unpacking tar archives, it may use the -j or -z + The arx tool relies on the presence of sed, tr, date, head, tar, + hexdump and sh. When unpacking tar archives, it may use the -j or -z (bzip2 and gzip, respectively) options of tar. Scripts have been tested - with dash and the GNU tools as well as the sh implementation and user- - land tools that are part of busybox. + with dash and the GNU tools as well as the sh implementation and + userland tools that are part of busybox. APPLICATION - The tmpx subcommand of arx offers a variety of options for bundling - code and a task to run. The shdat subcommand exposes the lower-level - functionality of encoding binary data in a shell script that outputs - that binary data, using HERE documents and some odd replacement rules + The tmpx subcommand of arx offers a variety of options for bundling + code and a task to run. The shdat subcommand exposes the lower-level + functionality of encoding binary data in a shell script that outputs + that binary data, using HERE documents and some odd replacement rules for nulls. - Scripts generated by tmpx and shdat may be fed to sh over STDIN to exe- - cute them. This can be helpful when using ssh and sudo to set up an + Scripts generated by tmpx and shdat may be fed to sh over STDIN to + execute them. This can be helpful when using ssh and sudo to set up an execution context; for example: arx tmpx ... | ssh user@host.com sudo sh - Scripts generated by tmpx will pass their arguments to the contained + Scripts generated by tmpx will pass their arguments to the contained script or command. To pass arguments when piping to sh, use -s: arx tmpx ... | ssh user@host.com sudo sh -s a b c - Some arguments to the generated script will be treated specially, - namely, --extract, --no-rm and --no-run. Please see the section on + Some arguments to the generated script will be treated specially, + namely, --extract, --no-rm and --no-run. Please see the section on Passing Arguments, below, for more information about these options. ARX COMMANDLINE PROCESSING - For all subcommands, when options overlap in their effect -- for exam- - ple, setting the output with -o -- the rightmost option takes prece- - dence. Whenever -h, -? or --help is present on the command line, help - is displayed and the program exits. + For all subcommands, when options overlap in their effect -- for + example, setting the output with -o -- the rightmost option takes + precedence. Whenever -h, -? or --help is present on the command line, + help is displayed and the program exits. - When paths are specified on an arx command line, they must be quali- - fied, starting with /, ./ or ../. This simplifies the command line syn- - tax, overall, without introducing troublesome ambiguities. + When paths are specified on an arx command line, they must be + qualified, starting with /, ./ or ../. This simplifies the command line + syntax, overall, without introducing troublesome ambiguities. TMPX The tmpx subcommand bundles together archives, environment settings and - an executable or shell command in to a Bourne-compatible script that - runs the command or executable in a temporary directory, after having + an executable or shell command in to a Bourne-compatible script that + runs the command or executable in a temporary directory, after having unpacked the archives and set the environment. - Any number of file path arguments may be specified; they will be inter- - preted as tar archives to include in bundled script. If - is given, - then STDIN will be included as an archive stream. If no arguments are - given, it is assumed that no archives are desired and only the command - and environment are bundled. + Any number of file path arguments may be specified; they will be + interpreted as tar archives to include in bundled script. If - is + given, then STDIN will be included as an archive stream. If no + arguments are given, it is assumed that no archives are desired and + only the command and environment are bundled. - The temporary directory created by the script is different for each - invocation, with a name of the form /tmp/tmpx--. - The timestamp format is %Y.%m.%dT%H.%M.%SZ, in UTC. One happy conse- - quence of this is that earlier jobs sort ASCIIbetically before later - jobs. After execution, the temporary directory is removed (or not, - depending on the -rm[10!_] family of options). + The temporary directory created by the script is different for each + invocation, with a name of the form /tmp/tmpx--. + The timestamp format is %Y.%m.%dT%H.%M.%SZ, in UTC. One happy + consequence of this is that earlier jobs sort ASCIIbetically before + later jobs. After execution, the temporary directory is removed (or + not, depending on the -rm[10!_] family of options). -rm0, -rm1, -rm_, -rm! - By default, the temporary directory created by the script + By default, the temporary directory created by the script will be deleted no matter the exit status status of the task. These options cause a script to be generated that deletes the - temporary directory only on success, only on failure, always + temporary directory only on success, only on failure, always (the default) or never. --shared - Causes the temporary directory to be identified by a hash of - the ARX archive, instead of by date and time. Different runs - of the same archive will share the same directory. Note that + Causes the temporary directory to be identified by a hash of + the ARX archive, instead of by date and time. Different runs + of the same archive will share the same directory. Note that this implies shared state and every disadvantage thereof. -b - Please see the documentation for this option, shared with + Please see the documentation for this option, shared with shdat, below. -o - By default, the generated script is sent to STDOUT. With -o, + By default, the generated script is sent to STDOUT. With -o, output is redirected to the given path. -e - Causes the file specified to be packaged as the task to be - run. A binary executable, a Ruby script or a longish shell + Causes the file specified to be packaged as the task to be + run. A binary executable, a Ruby script or a longish shell script all fit here. - In addition to these options, arguments of the form VAR=VALUE are rec- - ognized as environment mappings and stored away in the script, to be + In addition to these options, arguments of the form VAR=VALUE are + recognized as environment mappings and stored away in the script, to be sourced on execution. - Without -e, the tmpx subcommand tries to find the task to be run as a - sequence of arguments delimited by a run of slashes. The following + Without -e, the tmpx subcommand tries to find the task to be run as a + sequence of arguments delimited by a run of slashes. The following forms are all recognized: arx tmpx ...some args... // ...command... arx tmpx ...some args... // ...command... // ...more args... arx tmpx // ...command... // ...some args... - The slash runs must have the same number of slashes and must be the - longest continuous runs of slashes on the command line. The command + The slash runs must have the same number of slashes and must be the + longest continuous runs of slashes on the command line. The command will be included as-is in a Bourne shell script. SHDAT - The shdat subcommand translates binary data in to a shell script which - outputs the binary data. The data is encoded in HERE documents in such - a way that data without NULs is not changed and that data with NULs is - minimally expanded: about 1% for randomish data like compressed tar- - balls and about 10% in pathological cases. + The shdat subcommand translates binary data in to a shell script which + outputs the binary data. The data is encoded in HERE documents in such + a way that data without NULs is not changed and that data with NULs is + minimally expanded: about 1% for randomish data like compressed + tarballs and about 10% in pathological cases. - The shdat subcommand can be given any number of paths, which will be + The shdat subcommand can be given any number of paths, which will be concatenated in the order given. If no path is given, or if - is given, then STDIN will be read. -b - The size of data chunks to place in each HERE document. The - argument is a positive integer followed by suffixes like B, - K, KiB, M and MiB, in the manner of dd, head and many other - tools. The default is 4MiB. This is unlikely to make a dif- - ference for you unless the generated script is intended to be - run on a memory-constrained system. + The size of data chunks to place in each HERE document. The + argument is a positive integer followed by suffixes like B, + K, KiB, M and MiB, in the manner of dd, head and many other + tools. The default is 4MiB. This is unlikely to make a + difference for you unless the generated script is intended to + be run on a memory-constrained system. -o - By default, the generated script is sent to STDOUT. With -o, + By default, the generated script is sent to STDOUT. With -o, output is redirected to the given path. EXAMPLES + # Installer script that preserves failed builds. git archive HEAD | bzip2 | arx tmpx -rm0 - // make install > go.sh # Now install as root; but don't log in as root. @@ -164,22 +167,22 @@ PASSING ARGUMENTS TO GENERATED SCRIPTS The scripts generated by tmpx treat some arguments as special, internal - options, to allow for inspecting them should there be a need to deter- - mine their contents. + options, to allow for inspecting them should there be a need to + determine their contents. --extract Unpack the data in the present directory and do nothing else. --no-rm - Run the script as normal but do not delete the generated tem- - porary directory. + Run the script as normal but do not delete the generated + temporary directory. --no-run - Unpack into a temporary directory as normal but do not run + Unpack into a temporary directory as normal but do not run the user's command. - To prevent arguments from being specially treated, use // in the argu- - ment list: + To prevent arguments from being specially treated, use // in the + argument list: a-tmpx-script.sh --no-rm // a b c --extract @@ -190,16 +193,16 @@ arx tmpx // printf "'%s\n'" '"$@"' | sh -s // ab c --no-rm NOTES - The timestamp is not the common ISO 8601 format, %Y-%m-%dT%H:%M:%SZ, - because of software and build processes that attach special meaning to + The timestamp is not the common ISO 8601 format, %Y-%m-%dT%H:%M:%SZ, + because of software and build processes that attach special meaning to colons in pathnames. BUGS - The command line parser offers no hints or help of any kind; it fails - with the simple message "argument error". The two most common mistakes + The command line parser offers no hints or help of any kind; it fails + with the simple message "argument error". The two most common mistakes I make are: - o Not qualifying paths with /, ./ or ../. + • Not qualifying paths with /, ./ or ../. - o Not specifying a subcommand (tmpx or shdat). + • Not specifying a subcommand (tmpx or shdat). diff --git a/model-scripts/tmpx.sh b/model-scripts/tmpx.sh --- a/model-scripts/tmpx.sh +++ b/model-scripts/tmpx.sh @@ -3,7 +3,6 @@ unset rm_ dir tmp=true ; run=true tmpdir= ; rm0=true ; rm1=true ; shared=false ; hash="" # To be set by tool. -token=`date -u +%FT%TZ | tr -d :-`-`hexdump -n4 -e '"%08x"'