.TH "starch" 1 "" "CCTools 7.0.9 FINAL" "Cooperative Computing Tools"

.SH NAME
.LP
\fBstarch\fP - STandalone application ARCHiver

.SH SYNOPSIS
.LP
\FC\fBstarch [options] <sfx_path>\fP\FT

.SH DESCRIPTION
.LP

\fBStarch\fP is a script that creates standalone application archives in the
form of self-extracting executables (\FCSFX\FT). Users may specify the command,
executables, libraries, data, and environment scripts associated with the
application by specifying the appropriate command line options or by using a
configuration file.  \fBstarch\fP is particularly useful for distributed
computing, in that it makes an executable portable across different
operating system variants.

.SH OPTIONS
.LP

To create a \FCSFX\FT, simply specify the name of the \FCSFX\FT to create along
with the <command> to execute and any other dependencies such as
<executables>, <libraries>, <data>, or <environment>
scripts.
.PP
If a <command> is specified, but no <executable> is passed, then the
first token in the <command> will be used as the executable.
.PP
By default, \FCstarch\FT will use \FCldd\FT to detect any necessary libraries
from the specified set of <executables> and include them in the \FCSFX\FT.
.LP
.TP
.B \ -A
.
Do not automatically detect library dependencies.
.TP
.BI \ -C \ <cfg>
.
Use configuration file.
.TP
.BI \ -c \ <cmd>
.
Specify command to execute.
.TP
.BI \ -d \ <npath:opath>
.
Add data (new path:old path).
.TP
.BI \ -e \ <env>
.
Add environment script.
.TP
.BI \ -l \ <lib>
.
Add library.
.TP
.BI \ -x \ <exe>
.
Add executable.
.TP
.B \ -h
.
Show help message and exit.
.TP
.B \ -v
.
Display verbose messages (default: False).

Once a \FCSFX\FT is generated, you can use it as a normal executable.

.SH CONFIGURATION FILE
.LP
The command line options may be stored in a configuration file and passed to
starch using the \FCstarch -C\FT option.  The format of the configuration file is as
follows:
.fam C
.nf
.nh
.IP "" 8
[starch]
executables = echo date hostname
libraries   = libz.so
data        = hosts.txt:/etc/hosts localtime:/etc/localtime images:/usr/share/pixmaps
command     = echo $(hostname) $(date $@)
.fi
.hy
.fam
.P

.SH ENVIRONMENT VARIABLES
.LP

The following environment variables will affect the execution of the \FCSFX\FT
generated by \FCstarch\FT:

.SS SFX_DIR
.LP
Determines the target directory where the \FCSFX\FT will be extracted.  By
default this is \FC/tmp/$hostname.$user.$basename.dir\FT.

.SS SFX_EXTRACT_ONLY
.LP
Only extract the \FCSFX\FT.  By default it is extracted and executed.

.SS SFX_EXTRACT_FORCE
.LP
Extract the \FCSFX\FT even if the \FCSFX_DIR\FT exists. This is disabled by
default to as an optimization to avoid unnecessarily extracting.

.SS SFX_KEEP
.LP
Keep extracted files.  By default the files will be removed after execution.

.SS SFX_UNIQUE
.LP

Use \FCmktempd\FT to generate a unique \FCSFX_DIR\FT target directory. This
will prevent \FCSFX_KEEP\FT from working properly since the names will change
in between invocations.

.SH EXIT STATUS
.LP
On success, returns zero.  On failure, returns non-zero.

.SH EXAMPLES
.LP

Package the date program:
.fam C
.nf
.nh
.IP "" 8
    $ starch -c date -x date date.sfx
.fi
.hy
.fam
.P

Package the date program using a configuration file:
.fam C
.nf
.nh
.IP "" 8
    $ cat data.cfg
    [starch]
    executables = date
    command = date
    $ starch -C date.cfg date.sfx
.fi
.hy
.fam
.P

Run standalone date program with parameters:
.fam C
.nf
.nh
.IP "" 8
    $ ./date.sfx +%s
.fi
.hy
.fam
.P

Only extract the archive:
.fam C
.nf
.nh
.IP "" 8
    $ env SFX_EXTRACT_ONLY=1 ./date.sfx
.fi
.hy
.fam
.P

Run and keep extracted directory:
.fam C
.nf
.nh
.IP "" 8
    $ env SFX_KEEP=1 ./date.sfx
.fi
.hy
.fam
.P

Run with unique directory:
.fam C
.nf
.nh
.IP "" 8
    $ env SFX_UNIQUE=1 ./date.sfx
.fi
.hy
.fam
.P

Advanced example involving a complex shell command:
.fam C
.nf
.nh
.IP "" 8
    $ starch -v -x tar -x rm  -c 'tar_test() { for f in $@; do if ! tar xvf $f; then exit 1; fi; done; rm $@'; }; tar_test' extract_and_remove.sfx
    $ ./extract_and_remove.sfx *.tar.gz
.fi
.hy
.fam
.P

.SH COPYRIGHT
.LP

The Cooperative Computing Tools are Copyright (C) 2003-2004 Douglas Thain and Copyright (C) 2005-2015 The University of Notre Dame.  This software is distributed under the GNU General Public License.  See the file COPYING for details.

.SH SEE ALSO
.LP


.IP \(bu 4
\fBCooperative Computing Tools Documentation\fP
.IP \(bu 4
\fBMakeflow User Manual\fP
.IP \(bu 4
\fBmakeflow(1)\fP \fBmakeflow_monitor(1)\fP \fBmakeflow_analyze(1)\fP \fBmakeflow_viz(1)\fP \fBmakeflow_graph_log(1)\fP \fBstarch(1)\fP \fBmakeflow_ec2_setup(1)\fP \fBmakeflow_ec2_cleanup(1)\fP