Installation¶

User installation¶

If you want to use Argbash locally, you have to download the software package and run the installation script.

Go to the release section of the GitHub project, choose the version to download, and download the source code package.
Unpack the contents of the archive. You can use the bin/argbash script without any installation (as it is described in the Quickstart), but you can proceed to the installation in order to be able to use argbash system-wide.
Go to the resources folder. There is a Makefile.
According to whether you have your $HOME/.local/bin folder in the PATH:
- If so, run make install PREFIX=$HOME/.local,
- else, run sudo make install PREFIX=/usr.
Note

If you want multiple Argbash versions installed in parallel, install them using make altinstall (and uninstall using make uninstall) commands. This will create argbash-X.Y.Z script under the bin directory, with argbash-X.Y, argbash-X and argbash symlinks pointing transitively to it. If you altinstall another version of Argbash, the common symlinks will be overwritten (i.e. at least argbash).

This way of installation won’t install the argbash-xtoy migration scripts.
Optional:
- Supply INSTALL_COMPLETION=yes as an installation argument to install bash completion for argbash to $(SYSCONFDIR)/bash_completion.d. The default SYSCONFDIR is /etc, but you may override it in the same way as you can override the PREFIX variable.
- To be able to let Argbash generate manpages, rst2man needs to be installed on your system. It’s part of the Python package docutils which can be installed on Debian/Ubuntu using sudo apt install python3-docutils.
- Run some checks by executing: make check (still in the resources folder). You should get a message All is OK at the bottom.

Argbash has this audience:

Users — people that use scripts that make use of Argbash.
Developers — people that use Argbash to write scripts.
Tinkerers — people that come in contact with Argbash internals, typically curious Developers.
bash >= 3.0 — this is obvious, everybody needs bash. There is only one exception — in cases of simple scripts, a POSIX shell s.a. dash will be enough for Users.
autoconf >= 2.63 — Argbash is written in a m4 language extension called m4sugar, which is contained in autoconf. Developers and Tinkerers need this. autoconf is available on Linux, macOS, BSDs and can be installed on MS Windows.
grep, sed, coreutils — The argbash script uses grep, sed, cat, and test. If you have autoconf, you probably have those already.
GNU Make >= 4.0 — the project uses Makefiles to perform a wide variety of tasks, although it is more of interest to Tinkerers.

Building Argbash¶

If you identify yourself as a tinkerer (i.e. you want to play with internals of Argbash), you may use a different set of steps:

Clone the Git repository: git clone https://github.com/matejak/argbash.git
Go to the resources directory consider running a develop install there, e.g. make develop PREFIX=$HOME/.local,

This type of installation ensures that whenever you make a change to the bin/argbash script in the repository, the argbash command always calls that bin/argbash script.
After you make modifications the source files (.m4 files in the src directory), you regenerate bin/argbash by running make ../bin/argbash in the resources directory.

If you let a bug through that prevents the argbash script to regenerate itself, run make bootstrap to regenerate it in a more robust way.
Remember to run make check in the resources directory often to catch bugs as soon as possible.

Argbash components¶

The Argbash package consists of these scripts:

argbash, the main part of Argbash. It is basically a wrapper around the autom4te utility that uses the Argbash “source code” located in the src directory. In course of an installation, both the script and the source are copied under the prefix — script goes to $PREFIX/bin and source to $PREFIX/lib/argbash.

The argbash script itself is generated using Argbash. It can be (re)generated using a Makefile that can be found in the resources folder.
argbash-xtoy scripts (x, y are major version numbers) that assist users in modifying their scripts in case that Argbash changes its API. For example, Argbash 2.1.4 (we say Argbash of major version 2) has argbash-1to2 script and Argbash of major version 3 will have scripts argbash-1to3 and argbash-2to3.
argbash-init is a quickstart script — it enables you to create a basic template for your script. Then, you just have to make some slight modifications, feed it to argbash and you are done.

The main Makefile¶

The Makefile in the resources folder can do many things:

Installation¶

make install [PREFIX=foo] runs the installation into the prefix you can specify (default is $(HOME)/.local). This will install the argbash script (notice the missing .sh extension) into $PREFIX/bin (and some support files into $PREFIX/lib/argbash).
make develop [PREFIX=foo] is similar to make install, but it installs a wrapper around the local bin/argbash, so any change to the file will be immediately reflected for everybody who uses the system-wide one. This is inspired by Python’s python setup.py develop pattern.
make uninstall [PREFIX=foo] inverse of the above.

Running argbash¶

make ../bin/argbash, make bootstrap makes (or updates) the argbash script (the script basically overwrites itself). Use the latter if previous update broke the current ../bin/argbash so it is not able to regenerate itself.
make examples compiles examples from .m4 files to .sh files in the examples folder.
make foo/bar.sh generates a script provided that there is a foo/bar.m4 file.
make foo/bar2.sh generates a script provided that there is a foo/bar.sh file.

Releasing¶

make check runs the tests.
make version VERSION=1.0.0 sets the project’s version to all corners of the project where it should go.
make release [VERSION=1.0.0] refreshes date in the ChangeLog and regenerates all of the stuff (and runs tests).
make tag tags the version.