diff options
Diffstat (limited to 'INSTALL.md')
| -rw-r--r-- | INSTALL.md | 120 |
1 files changed, 91 insertions, 29 deletions
@@ -6,19 +6,33 @@ Copyright © 2016 Paul Garlick <[pgarlick@tourbillion-technology.com](mailto:pga 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. +*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. +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 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*. +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. +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 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: +Second, set the environment variables to 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 environment variables @@ -29,7 +43,8 @@ Second, set the environment variables to access to the ``guix`` executable. Thi GUIX_LOCPATH=$HOME/.guix-profile/lib/locale } -To continue, start a new shell (or ``source`` the modified .bashrc file), move to the download directory and type: +To continue, start a new shell (or ``source`` the modified .bashrc file), move +to the download directory and type: $ startGuix @@ -37,21 +52,33 @@ 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: +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 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. -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). -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 .bashrc 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 to set up the environment: +By default, Nix modifies the users .bashrc 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 to set up the +environment: startNix () { # set Nix environment variables @@ -60,15 +87,24 @@ By default, Nix modifies the users .bashrc file to automatically set up the Nix 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: +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 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 -Nix applications that use 3D graphics acceleration need help in finding the system libraries and drivers. The paths vary according to operating system and graphics card. For a CentOS 6 system, for example, with an Intel graphics card six extra paths need to be defined. This can be accomplished with an alias or a shell function. Using the shell function approach for the CentOS example, the following lines added to the .bashrc file provide a function that sets the necessary environment variables and runs the FreeCAD application: +Nix applications that use 3D graphics acceleration need help in finding the +system libraries and drivers. The paths vary according to operating system and +graphics card. For a CentOS 6 system, for example, with an Intel graphics card +six extra paths need to be defined. This can be accomplished with an alias or +a shell function. Using the shell function approach for the CentOS example, +the following lines added to the .bashrc file provide a function that sets the +necessary environment variables and runs the FreeCAD application: freecad () { FONTCONFIG_PATH="$HOME/.nix-profile/etc/fonts/fonts.conf" \ @@ -85,43 +121,69 @@ Nix applications that use 3D graphics acceleration need help in finding the syst 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: +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 +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: +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): +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: +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: +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: +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. +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 |