# Tweed.INSTALL
Copyright © 2016, 2017 Paul Garlick <[pgarlick@tourbillion-technology.com](mailto:pgarlick@tourbillion-technology.com)>

  Copying and distribution of this file, with or without modification,
  are permitted in any medium without royalty provided the copyright
  notice and this notice are preserved.  This file is offered as-is,
  without any warranty.

*TWEED* makes use of three package managers.  As a consequence, there are three
parts to the installation process.  The parts can be followed in any order.

As a preliminary step, download the *TWEED* repository.  Use either the 'git
clone' method or download the tar file.  There are three documentation files, a
LICENSE file, an AUTHORS file, a script and three configuration files, one for
each package manager.

Part 1: GNU Guix packages
-------------------------
GNU Guix is a transactional package manager.  It can be used to install a
complete GNU/Linux operating system.  Transactional here means that all
upgrades are performed as a sequence of atomic operations; the upgrade either
completes fully or not at all.  This provides protection against power loss in
the middle of an upgrade; the system can reboot to its previous configuration.

GNU Guix may also be used to install packages on a computer running a different
operating system.  The GNU Guix package files are installed alongside the
system files.  This is how GNU Guix is used in *TWEED*.

First, install GNU Guix; follow the installation instructions in the [GNU Guix
manual](https://www.gnu.org/software/guix/manual/html_node/Installation.html#Installation).
There are two options; the binary installation method is the easier of the two.

Second, set the environment variables to give access to the ``guix`` executable.
This can be done using a shell function.  For a *bash* shell, for example, the
following function can be defined in the .bashrc file:

	startGuix () {
		# set GUIX_PROFILE variable
                GUIX_PROFILE="$HOME/.guix-profile"
		# set paths according to profile
		if [ -e "$GUIX_PROFILE/etc/profile" ]; then
		    source "$GUIX_PROFILE/etc/profile"
		fi
                # set path for locale
                export GUIX_LOCPATH=$GUIX_PROFILE/lib/locale
	}

To continue, start a new shell (or ``source`` the modified .bashrc file), move
to the download directory and type:

	$ startGuix

Then, to install the *TWEED* packages, type.

	$ guix package --manifest=tweed.guix.scm

Aliases can be defined to start the applications.  For example, for the grid
generator Gmsh, the following alias sets ``FONTCONFIG_PATH`` to the correct
location before executing the ``gmsh`` command:

	$ alias gmsh="FONTCONFIG_PATH=$HOME/.guix-profile/etc/fonts gmsh"


Part 2: Nix packages
--------------------
The Nix package manager is related to GNU Guix.  Nix is the forerunner to GNU
Guix and provides some of the code on which GNU Guix is based.  Many
characteristics are common to both package managers.  For example, Nix forms
the basis for NixOS, a full GNU/Linux operating system.  Nix upgrades are also
atomic.

The Nix package manager can be installed alongside an operating system other
than NixOS.  It does not conflict with GNU Guix; the two package managers store
their files separately.

To install the Nix components of *TWEED*, first install Nix.  Follow the
installation procedure shown on the [Nix
website](http://nixos.org/nix/download.html).  

By default, Nix modifies the users .bash_profile file to automatically set up
the Nix environment for new invocations of the shell.  Should the user prefer,
these lines can be commented out and a shell function defined in the .bashrc
file instead:

	startNix () {
		# set Nix environment variables
		if [ -e "$HOME/.nix-profile/etc/profile.d/nix.sh" ]; then
		    source "$HOME/.nix-profile/etc/profile.d/nix.sh"
		fi
	}

The user then has control over whether and when the Nix environment is set up.
If the function is defined, then to use the Nix executables, or later the
applications installed with Nix, first type:

	$ startNix

Nix uses the ``nix-env`` command to control the package environment.  To
install the *TWEED* packages, use the following command:

	$ nix-env -f tweed.nix -i

It is necessary to set an extra environment variable for Nix applications that
use 3D graphics acceleration.  The extra variable defines the path to the
directory in the Nix store that contains the graphics drivers.  This can
conveniently be accomplished with an alias or a shell function.  Using the
shell function approach, for the FreeCAD application, the following lines added
to the ~/.bashrc file provide a function that sets the necessary environment
variable and runs the application:
	
	freecad () {
                LIBGL_DRIVERS_PATH=$(nix-build --no-out-link -A mesa_drivers $HOME/.nix-defexpr/channels/nixpkgs)/lib/dri \
		$HOME/.nix-profile/bin/FreeCAD
	}


Part 3: HashDist packages
-------------------------
HashDist is a package manager written in the Python programming language.  It
is similar to GNU Guix and Nix in that each item in the software store is
identified by a cryptographic hash.  By default, HashDist creates a
subdirectory in the user's home directory.  Packages installed by HashDist are
stored in a hierarchy rooted at this subdirectory.

There are two parts to a HashDist installation; installing the HashDist
software and installing a HashStack, a set of instructions for building
packages.  The users HashDist profile defines which exact packages to build and
install.  In our case we will be using the ``tweed.hashdist.yaml`` file.

First, install HashDist.  Requirements for HashDist are listed on the [FEniCS
Project
website](https://fenicsproject.org/download/installation_using_hashdist.html).
One of the requirements is the Git version control system.  This is used for
the initial installation.  In a suitable subdirectory of the user's home
directory type the following command:

	$ git clone https://github.com/hashdist/hashdist.git

This installs the ``hit`` command, which is used to build and install packages.
To make this command available add the HashDist ``bin`` directory to the user's
$PATH.  For example, if HashDist has been installed in a subdirectory named
``repos`` then add the following lines to the user's .profile file
	
	if [ -d "$HOME/repos/hashdist/bin" ]; then
	    PATH="$HOME/repos/hashdist/bin:$PATH"
	fi

Next, install the HashStack.  A FEniCS fork of the HashDist HashStack is
available.  It is kept up-to-date with the latest FEniCS developments.  In a
suitable directory (``$HOME/repos`` again, for example), install the FEniCS
version with the command:

	$ git clone https://github.com/FEniCS/hashstack.git

Start a new shell or Initialize HashDist to create the store root directory
(``~/.hashdist`` by default):

	$ hit init-home

To prepare to install the packages for *TWEED*, change to the HashStack
directory and copy the *TWEED* profile:

	$ cd $HOME/repos/hashstack
	$ cp .../tweed.hashsdist.yaml default.yaml

Parts of the build process may be executed in parallel.  For a system with N
cores, use the command:

	$ hit build -jM

where M is less than N.  A symbolic link named ``default`` is created in the
HashStack directory.  This link points to the newly created HashDist profile.
The script ``tweed.hashdist.post-install`` is provided to read the link and
create a new file containing the definitions of the necessary environment
variables.  From the HashStack directory run the command:

	$ sh tweed.hashdist.post-install

The file generated, named ``hashdist.sh,`` is put in a new directory
``.hashdist-profile``.  Create a shell function to read and execute the
commands in this file.  Store the function in the .bashrc file.

	startHashDist () {
		# set HashDist environment variables
		if [ -e "$HOME/.hashdist-profile/hashdist.sh" ]; then
		    source "$HOME/.hashdist-profile/hashdist.sh"
		fi
	}

Now, to use the applications installed with HashDist, first type:

	$ startHashDist