Skip to content

some minor reformating in installation doc page #2

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
branfosj merged 3 commits into from
Jun 18, 2021
Merged

some minor reformating in installation doc page #2

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
9a227b6
some minor reformating in installation doc page
boegel Jun 18, 2021
3fe186b
add ref to $EB_PYTHON section
boegel Jun 18, 2021
d0d6d60
fix formatting issue
boegel Jun 18, 2021
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
76 changes: 60 additions & 16 deletions docs/Installation.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -62,6 +62,8 @@ Install EasyBuild with::

pip install easybuild

You may need to tweak this command a bit, depending on your setup, see :ref:`more_pip`.

.. note::
There are various other ways of installing Python packages, which we won't cover here.
If you are familiar with other tools like ``virtualenv`` or ``pipenv``, feel free to use those
Expand All @@ -77,10 +79,10 @@ For example::
$ module list

Currently Loaded Modules:
1) EasyBuild/1.16.1
1) EasyBuild/4.4.0

$ eb --version
This is EasyBuild 1.16.1 (framework: 1.16.1, easyblocks: 1.16.1) on host example.local
This is EasyBuild 4.4.0 (framework: 4.4.0, easyblocks: 4.4.0) on host example.local

.. tip::

Expand All @@ -90,8 +92,8 @@ For example::
may make a big difference, if you have installed both versions 1.9.0 and 1.15.2,
with respect to what is the version being loaded by default.

You can also run ``eb --show-config`` to see the default EasyBuild configuration. See the Configuring EasyBuild section
for more information :ref:`configuring_easybuild`
You can also run ``eb --show-system-info`` to see system information relevant to EasyBuild,
or run``eb --show-config`` to see the default EasyBuild configuration (see also :ref:`configuring_easybuild`).

.. _updating:

Expand All @@ -102,22 +104,42 @@ To upgrade to a newer EasyBuild version than the one currently installed:

* ``pip install --upgrade easybuild`` will upgrade EasyBuild to the latest release.

.. _advancedpip:
.. _more_pip:

Advanced pip install options
Additional pip install options
~~~~~~~~~~~~

For the ``pip`` install, you may wish to slightly change this command depending on the context and your personal preferences:

* To install EasyBuild *system-wide*, you can use ``sudo`` (if you have admin privileges): ``sudo pip install easybuild``
* to install EasyBuild *system-wide*, you can use ``sudo`` (if you have admin privileges):

.. code:: sh

sudo pip install easybuild

* To install EasyBuild *in your personal home directory*, you can use the ``--user`` option:

.. code:: sh

pip install --user easybuild

* To install EasyBuild *in your personal home directory*, you can use the ``--user`` option: ``pip install --user easybuild``
This will result in an EasyBuild installation in ``$HOME/.local/``.

* To install EasyBuild in a *specific directory* you can use the ``--prefix`` option: ``pip install --prefix _PREFIX_ easybuild``
* To install EasyBuild in a *specific directory* you can use the ``--prefix`` option:

.. code:: sh

pip install --prefix _PREFIX_ easybuild

In this command, you should replace '``_PREFIX_``' with the location where you want to have EasyBuild installed
(for example, ``$HOME/tools`` or ``/tmp/$USER``).

Keep in mind that you may need to update your environment too when using ``--user`` or ``--prefix``,
see :ref:`more_pip_env`.


.. _more_pip_pip3:

``pip`` vs ``pip3``
~~~~~~~~~~~~

Expand All @@ -126,11 +148,24 @@ available. Or maybe ``pip`` is not available at all, and only "versioned" ``pip`
available.

If you (only) have ``pip3`` available, you can replace ``pip`` with ``pip3`` in any of the ``pip install`` commands
above.
above:

.. code:: sh

pip3 install easybuild

If you want to ensure that you are using the ``pip`` installation that corresponds to the Python 3 installation
that you intend to use, you can use ``python3 -m pip`` rather than ``pip3``.

.. code:: sh

python3.6 -m pip install easybuild

Note that you may also need to instruct the ``eb`` command to use the correct Python version at runtime,
via ``$EB_PYTHON`` (see :ref:`more_pip_env_EB_PYTHON`).

.. _more_pip_env:

Updating your environment
~~~~~~~~~~~~

Expand All @@ -143,20 +178,24 @@ This is not required if you did a system-wide installation in a standard locatio
Keep in mind that you will have to make these environment changes again if you start a new shell session.
To avoid this, you can update one of the shell startup scripts in your home directory (``.bashrc`` for example).

.. _more_pip_env_PATH:

Updating ``$PATH``
~~~~~~~~~~~~

Update the ``$PATH`` environment variable to make sure the ``eb`` command is available::

export PATH=_PREFIX_/bin:$PATH

**Replace '``_PREFIX_``' in this command** with the directory path where EasyBuild was installed into
**Replace** ``_PREFIX_`` **in this command** with the directory path where EasyBuild was installed into
(use ``$HOME/.local`` if you used ``pip install --user``).

This is not required if you installing EasyBuild in a standard system location.

You can check with the ``which eb`` command to determine whether or not you need to update the ``$PATH`` environment variable.

.. _more_pip_env_PYTHONPATH:

Updating ``$PYTHONPATH``
~~~~~~~~~~~~

Expand Down Expand Up @@ -184,6 +223,7 @@ For example::
# update $PYTHONPATH if EasyBuild was installed in $HOME/tools with Python 3.6
export PYTHONPATH=$HOME/tools/lib/python3.6/site-packages:$PYTHONPATH

.. _more_pip_env_EB_PYTHON:

Setting ``$EB_PYTHON``
~~~~~~~~~~~~
Expand All @@ -200,6 +240,8 @@ For example, to ensure that ``eb`` uses ``python3.6``::
export EB_PYTHON=python3.6


.. _more_pip_env_EB_VERBOSE:

Setting ``$EB_VERBOSE``
~~~~~~~~~~~~

Expand Down Expand Up @@ -278,7 +320,7 @@ environment variable ``$MODULEPATH``)::

module use _PREFIX_/modules/all

**Replace '``_PREFIX_``'** with the path to the directory that you used when running :ref:`eb_as_module_step2`
**Replace** ``_PREFIX_`` with the path to the directory that you used when running :ref:`eb_as_module_step2`
(for example, ``$HOME/easybuild``).

Then, load the EasyBuild module to update your environment and make EasyBuild available for use::
Expand Down Expand Up @@ -308,12 +350,14 @@ Required dependencies

* `Python <http://python.org>`_:

* Python 2.7, or Python 3.x (>= 3.5). Since Python 2 is end-of-life (https://www.python.org/doc/sunset-python-2/) we recommend
using Python 3 if it is available
* Python 2.7, or Python 3.x (>= 3.5);

* since Python 2 is end-of-life (https://www.python.org/doc/sunset-python-2/) we strongly recommend
using Python 3 if it is available;

* no third-party Python packages are strictly required (the Python standard library is sufficient)
* no third-party Python packages are strictly required (the Python standard library is sufficient);

* for some *specific* EasyBuild features additional Python packages are required however, see :ref:`optional_python_packages`
* for some *specific* EasyBuild features additional Python packages are required however, see :ref:`optional_python_packages`;

* a **modules tool**: Tcl(/C) environment modules or Lmod

Expand Down