starch(1)

NAME

starch - STandalone application ARCHiver

SYNOPSIS

starch [options] <sfx_path>

DESCRIPTION

Starch is a script that creates standalone application archives in the form of self-extracting executables (SFX). 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. starch is particularly useful for distributed computing, in that it makes an executable portable across different operating system variants.

OPTIONS

To create a SFX, simply specify the name of the SFX to create along with the <command> to execute and any other dependencies such as <executables>, <libraries>, <data>, or <environment> scripts.

If a <command> is specified, but no <executable> is passed, then the first token in the <command> will be used as the executable.

By default, starch will use ldd to detect any necessary libraries from the specified set of <executables> and include them in the SFX.

  • -A
    Do not automatically detect library dependencies.
  • -C <cfg>
    Use configuration file.
  • -c <cmd>
    Specify command to execute.
  • -d <npath:opath>
    Add data (new path:old path).
  • -e <env>
    Add environment script.
  • -l <lib>
    Add library.
  • -x <exe>
    Add executable.
  • -h
    Show help message and exit.
  • -v
    Display verbose messages (default: False).

Once a SFX is generated, you can use it as a normal executable.

CONFIGURATION FILE

The command line options may be stored in a configuration file and passed to starch using the starch -C option. The format of the configuration file is as follows:

[starch]
executables = echo date hostname
libraries   = libz.so
data        = hosts.txt:/etc/hosts localtime:/etc/localtime images:/usr/share/pixmaps
command     = echo $(hostname) $(date $@)

ENVIRONMENT VARIABLES

The following environment variables will affect the execution of the SFX generated by starch:

SFX_DIR

Determines the target directory where the SFX will be extracted. By default this is /tmp/$hostname.$user.$basename.dir.

SFX_EXTRACT_ONLY

Only extract the SFX. By default it is extracted and executed.

SFX_EXTRACT_FORCE

Extract the SFX even if the SFX_DIR exists. This is disabled by default to as an optimization to avoid unnecessarily extracting.

SFX_KEEP

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

SFX_UNIQUE

Use mktempd to generate a unique SFX_DIR target directory. This will prevent SFX_KEEP from working properly since the names will change in between invocations.

EXIT STATUS

On success, returns zero. On failure, returns non-zero.

EXAMPLES

Package the date program:

    $ starch -c date -x date date.sfx

Package the date program using a configuration file:

    $ cat data.cfg
    [starch]
    executables = date
    command = date
    $ starch -C date.cfg date.sfx

Run standalone date program with parameters:

    $ ./date.sfx +%s

Only extract the archive:

    $ env SFX_EXTRACT_ONLY=1 ./date.sfx

Run and keep extracted directory:

    $ env SFX_KEEP=1 ./date.sfx

Run with unique directory:

    $ env SFX_UNIQUE=1 ./date.sfx

Advanced example involving a complex shell command:

    $ 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

The Cooperative Computing Tools are Copyright (C) 2022 The University of Notre Dame. This software is distributed under the GNU General Public License. See the file COPYING for details.

SEE ALSO

CCTools