A micro installer, intended to be very small, light weight and configurable. Designed for the installation of small, simple projects.
NB: tiny-install is currently under development. See the Remaining work section for current status.
tiny-install is little more than a glorified file-copying/linking script as described in a project's configuration file. It does not handle dependency installation or checking, versioning, updating or uninstalling. These would all require a central database of installed projects (short of fixed install locations).
© Copyright 2017 Jonathan Simmonds
≥ Python 2.3 (if using < 2.7 place
argparse.py alongside install
).
All files are licensed under the MIT license.
Only the file install
makes up the functional part of the project and may be
distributed alone providing the copyright & license header in it remains
intact.
If you have a project which can be installed with tiny-install, assuming
install
is on the PATH
, simply run one of:
-
cd examples/simple install .
-
install examples/simple
-
install examples/simple-zipped.zip
-
install https://github.com/jonsim/tiny-install/raw/master/examples/simple-zipped.zip
-
install git@github.com:jonsim/some-project.git
Alternatively, if install
is not on the PATH
, but is distributed in the root
directory of the project:
-
cd some/project ./install
-
./some/project/install
install
accepts the following command line options:
Option | Effect |
---|---|
-h , --help |
Show the help text. |
-y , --yes |
Run non-interactively, using all default arguments. |
-l , --links |
Create symbolic links instead of copying files. |
To enable tiny-install to install a project as above:
- Add an install config file in the root folder of your project. This file may
be called:
INSTALL.CFG
,install.cfg
,.INSTALL.CFG
or.install.cfg
. For consistency the first version is preferred. - Describe in this file the various modules of the project and their installation locations. See the Config file syntax section for information on this.
- (Optionally) give your users some kind of hint on how to install. Choose the
install pattern which most makes sense for your
project. As tiny-install is licensed under
the MIT license
you are free to modify and/or distribute it with your application as you see
fit providing the copyright & license header in
install
remains intact. You may redirect users to this page or reproduce in part or in full this documentation on your project's page. You need not provide attribution for any part of this documentation reproduced, nor even at all.
Config files have a basic INI-style syntax. Sections are given in
[square-brackets]
, followed by key = value
or key: value
pairs (which may
not be indented). Comments may use #
or ;
(only the latter may be used for
inline comments). Refer to the documentation for the
ConfigParser library (a
builtin used for the parsing) for further information.
All paths may contain a reference to the special ~
directory which will
evaluate to the (platform appropriate) user's home directory. All paths should
use UNIX style /
separators.
Every config file must contain the special $PROJECT$
section. All other
sections are module sections.
It is recommended, but not necessary, to make this the first section in the file.
Available key | Description | Default if absent |
---|---|---|
name |
The project's name. Displayed in installation text. | N/A (must be provided) |
description |
A brief description of the project. Displayed in the installation text. | N/A (must be provided) |
root |
The root installation directory. This is optional, its value can be accessed as %(root)s in all other values. Specifying this alone does nothing. This is actually a special-case of all other keys (below) which allows user-overrides with the override_root key. |
Empty string |
override_root |
yes if the user can override the root installation directory. |
no |
all other keys | All other key-value pairs in this section are pulled verbatim and stored. As with root , these keys can then be accessed as %(key-name)s in all other values. Unlike root these are not user overrideable. This is useful to reduce replication. The key names must not clash with those permitted in module sections. |
N/A (undefined) |
The name of these sections denotes the name of the module. Names must be unique.
The only restricted names are $PROJECT$
and DEFAULT
.
Available key | Description | Default if absent |
---|---|---|
name |
The module's name. This only need be provided if for some reason it cannot be represented in the section name (i.e. it is a restricted name or contains special characters). | Section name |
optional_module |
yes if the user may opt out of installing this module. |
no |
default_module |
yes if this module should be installed by default (ignored if the module is not optional). |
yes |
source |
Path, relative to the config file, to the item comprising the module. This may be a file or a directory (in which case it is copied recursively). | %(name)s |
target |
Absolute path to the target of this item. The installation will rename to the basename, so must include the name of the destination. As this path is absolute use of %(root)s is desireable. |
%(root)s/%(source)s |
override_target |
yes if the user can override the target destination. |
no |
All keys within a section are accessible within the scope of that section
via the %(key-name)s
syntax - e.g. %(name)s
, %(source)s
. These will have
their default value if they are not otherwise specified (so you need not define
name
to have it correctly interpolated).
The examples
directory in this repository contains several examples of varying
complexity which those interested are encouraged to explore. The example in
examples/simple
is replicated below.
examples/simple
+-- base-file.txt
+-- INSTALL.CFG
+-- module-1
| `- file.txt
`-- module-2
`- file.txt
Contents of INSTALL.CFG
:
[$PROJECT$]
name = simple example
description = A very simple example project
root = ~/simple-example
override_root = yes
[base]
source = base-file.txt
target = %(root)s/base.txt
[module-1]
target = %(root)s/first-module
override_target = yes
[module-2]
optional_module = yes
default_module = yes
source = module-2
target = %(root)s/second-module
override_target = yes
Note that I override some values below during installation:
$ install examples/simple
simple example installer
------------------------
A very simple example project
Installation directory [default: ~/simple-example]:
Installing to ~/simple-example
Installing base...
Installed
Installing module-1...
Install directory [default: ~/simple-example/first-module]: ~/simple-example/1
Installed
Install module-2 [Y/n]? n
Skipped
simple example installed
Note the altered values are present in the installed structure:
/home/jon/simple-example
+-- base.txt
`-- 1
`- file.txt
- Provide more friendly error output
- Add further examples
- Installation from a git repository
- Write out module install locations
- Consider uninstallation (which would require keeping a record of installation)
- Consider updating (which would require keeping a record of installation)
- Consider dependency checking