arx 0.3.2 → 0.3.3
raw patch · 14 files changed
+228/−246 lines, 14 filesdep −bytestring-numsdep ~attoparsecdep ~basedep ~blaze-builderPVP: major bump suggested
API removals or changes: PVP suggests a major version bump
Dependencies removed: bytestring-nums
Dependency ranges changed: attoparsec, base, blaze-builder, bytestring, containers, file-embed, hashable, parsec, process, shell-escape, template-haskell
API changes (from Hackage documentation)
- System.Posix.ARX.CLI: die :: () => ByteString -> IO b
+ System.Posix.ARX.CLI: die :: ByteString -> IO b
- System.Posix.ARX.CLI.CLTokens: sizeBounded :: forall b. (Bounded b, Integral b) => Parser b
+ System.Posix.ARX.CLI.CLTokens: sizeBounded :: (Bounded b, Integral b) => Parser b
Files
- README +88/−85
- System/Posix/ARX.hs +0/−1
- System/Posix/ARX/CLI.hs +0/−1
- System/Posix/ARX/CLI/CLTokens.hs +0/−1
- System/Posix/ARX/CLI/Options.hs +0/−1
- System/Posix/ARX/HEREDat.hs +1/−3
- System/Posix/ARX/Programs.hs +1/−3
- System/Posix/ARX/Sh.hs +0/−1
- System/Posix/ARX/TMPXTools.hs +0/−1
- arx.cabal +29/−29
- docs/blessed/arx.man +19/−33
- docs/blessed/arx.txt +88/−85
- model-scripts/tmpx.sh +1/−1
- version +1/−1
README view
@@ -1,4 +1,5 @@ SYNOPSIS+ arx (-h | -[?] | --help) arx (-v | --version) arx shdat (-b <size>)? (-o <output file>)? < input@@ -6,144 +7,146 @@ arx tmpx <option,archive>* (//+ <command> (//+ <option,archive>*)?)? 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-<timestamp>-<randomhex>.- 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-<timestamp>-<randomhex>.+ 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 <size>- Please see the documentation for this option, shared with+ Please see the documentation for this option, shared with shdat, below. -o <path>- 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 <path>- 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 <size>- 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 <path>- 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).
System/Posix/ARX.hs view
@@ -10,4 +10,3 @@ import System.Posix.ARX.Programs import System.Posix.ARX.Sh import System.Posix.ARX.Tar-
System/Posix/ARX/CLI.hs view
@@ -181,4 +181,3 @@ | otherwise = Char8.hPutStr stderr (b `Char8.snoc` '\n') die msg = err msg >> exitFailure-
System/Posix/ARX/CLI/CLTokens.hs view
@@ -188,4 +188,3 @@ -} sizeBounded :: forall b . (Bounded b, Integral b) => Parser b sizeBounded = fromInteger . min (toInteger (maxBound :: b)) <$> size-
System/Posix/ARX/CLI/Options.hs view
@@ -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-
System/Posix/ARX/HEREDat.hs view
@@ -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. -}-
System/Posix/ARX/Programs.hs view
@@ -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--
System/Posix/ARX/Sh.hs view
@@ -66,4 +66,3 @@ class Raw t where raw :: t -> ByteString-
System/Posix/ARX/TMPXTools.hs view
@@ -79,4 +79,3 @@ isHole :: ByteString -> Bool isHole line = "# To be set by tool." `Bytes.isSuffixOf` line-
arx.cabal view
@@ -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
docs/blessed/arx.man view
@@ -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 <size>)? (\-o <output file>)? < input arx shdat (\-b <size>)? (\-o <output file>)? <input file>+ arx tmpx <option,archive>* (//+ <command> (//+ <option,archive>*)?)?-.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\&.
docs/blessed/arx.txt view
@@ -1,4 +1,5 @@ SYNOPSIS+ arx (-h | -[?] | --help) arx (-v | --version) arx shdat (-b <size>)? (-o <output file>)? < input@@ -6,144 +7,146 @@ arx tmpx <option,archive>* (//+ <command> (//+ <option,archive>*)?)? 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-<timestamp>-<randomhex>.- 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-<timestamp>-<randomhex>.+ 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 <size>- Please see the documentation for this option, shared with+ Please see the documentation for this option, shared with shdat, below. -o <path>- 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 <path>- 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 <size>- 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 <path>- 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).
model-scripts/tmpx.sh view
@@ -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"' </dev/urandom` opts() { cmd="$1" ; shift n=$#@@ -41,6 +40,7 @@ rm_=false dir="$tmpdir"/tmpx-"$hash" else+ token=`date -u +%FT%TZ | tr -d :-`-`hexdump -n4 -e '"%08x"' </dev/urandom` dir="$tmpdir"/tmpx-"$token" fi : ${rm_:=true}
version view
@@ -1,1 +1,1 @@-0.2.3+0.3.2