← Back to branch summary

~ubuntu-branches/ubuntu/trusty/cctools/trusty-proposed

« back to all changes in this revision

Viewing changes to python/starch/README.rst

  • Committer: Package Import Robot
  • Author(s): Michael Hanke
  • Date: 2011-10-26 11:51:10 UTC
  • mfrom: (1.1.3)
  • Revision ID: package-import@ubuntu.com-20111026115110-5pc2qxp03chldcdi
Tags: 3.4.0-1
* New upstream release.
* Improve DEP5 compliance of debian/copyright.
* Added patch to make "starch" use python instead of python2 as interpreter.
* Tighten build-dependencies (added swig and m4).
* Enable MPI-support for work-queue.
* Move to dh_python2.
* Split Python-bindings for workqueue into a dedicated package and build
  them for all supported Python versions.

Show diffs side-by-side

added added

removed removed

Lines of Context:
python/starch/README.rst
1
 
Starch - README
2
 
===============
3
 
 
4
 
Overview
5
 
--------
6
 
 
7
 
Starch is a script that creates standalone application archives in the form of
8
 
self-extracting executables (SFX).  Users may specify the command, executables,
9
 
libraries, data, and environment scripts associated with the application by
10
 
specifying the appropriate command line options or by using a configuration
11
 
file and passing it to starch.
12
 
 
13
 
Installation
14
 
------------
15
 
 
16
 
Use the standard Python setup.py script as so::
17
 
 
18
 
    $ ./setup.py install
19
 
 
20
 
Usage
21
 
-----
22
 
 
23
 
::
24
 
 
25
 
    Usage: starch.py [options] <sfx_path>
26
 
 
27
 
    Options:
28
 
        -h, --help      show this help message and exit
29
 
        -c cmd          command to execute
30
 
        -x exe          add executable
31
 
        -l lib          add library
32
 
        -d npath:opath  add data (new path:old path)
33
 
        -e env          add environment script
34
 
        -C cfg          configuration file
35
 
        -a              automatically detect library dependencies (default: True)
36
 
        -A              do not automatically detect library dependencies
37
 
        -v              display verbose messages (default: False)
38
 
 
39
 
Configuration File
40
 
------------------
41
 
 
42
 
Instead of specifying the command, executables, libraries, data, and
43
 
environment options on the command line, users may specify the settings in a
44
 
simple INI-style configuration file and pass that to starch.  A simple example
45
 
configuration file looks like so::
46
 
    
47
 
    [starch]
48
 
    executables = echo date hostname
49
 
    libraries   = libz.so
50
 
    data        = hosts.txt:/etc/hosts localtime:/etc/localtime images:/usr/share/pixmaps
51
 
    command     = echo $(hostname) $(date $@)
52
 
 
53
 
In this example, we specify three executables: ``echo``, ``date``, and
54
 
``hostname``.  We include the ``libz.so`` library and a collection of data
55
 
files.  In this case, we copy ``/etc/hosts`` to ``hosts.txt``,
56
 
``/etc/localtime`` to ``localtime``, and we recursively copy the
57
 
``/usr/share/pixmaps`` directory to ``images``.  Finally, we set our command to
58
 
simply print out the hostname and date.
59
 
 
60
 
Environmental Variables
61
 
-----------------------
62
 
 
63
 
The following environmental variables modify the behavior of the generated SFX
64
 
application.
65
 
 
66
 
- **SFX_DIR**:           Target directory where SFX will be extracted.
67
 
- **SFX_EXTRACT_ONLY**:  Only extract the SFX (by default it will be extracted and ran).
68
 
- **SFX_EXTRACT_FORCE**: Extract the SFX even if target directory exists.
69
 
- **SFX_KEEP**:          Keep extracted files (by default the files will be removed after execution).
70
 
- **SFX_UNIQUE**:        Use ``mktempd`` to generate unique SFX target directory.  This will prevent **SFX_KEEP** from working properly since the names will keep on changing.
71
 
 
72
 
Examples
73
 
--------
74
 
 
75
 
Package the date program::
76
 
 
77
 
   $ starch -x date date.sfx
78
 
 
79
 
Package the date program using a configuration file::
80
 
 
81
 
   $ starch -C date.cfg date.sfx
82
 
 
83
 
Run standalone date program::
84
 
 
85
 
   $ ./date.sfx +%s
86
 
 
87
 
Only extract the archive::
88
 
 
89
 
   $ env SFX_EXTRACT_ONLY=1 ./data.sfx
90
 
 
91
 
Run and keep extracted directory::
92
 
    
93
 
   $ env SFX_KEEP=1 ./data.sfx
94
 
 
95
 
Run with unique directory::
96
 
 
97
 
   $ env SFX_UNIQUE=1 ./data.sfx
98
 
 
99
 
Advanced example involving a complex shell command::
100
 
 
101
 
   $ starch -v -x tar -x rm extract_and_remove.sfx 'for f in $@; do if ! tar xvf $f; then exit 1; fi; done; rm $@'
102
 
   $ ./extract_and_remove.sfx *.tar.gz