Skip to content
Snippets Groups Projects
Commit 8884eb1b authored by Amir MOHAMMADI's avatar Amir MOHAMMADI
Browse files

update installation and help documents

parent b926cf0e
No related branches found
No related tags found
No related merge requests found
Pipeline #58814 failed
...@@ -42,7 +42,6 @@ by using public channels. Here is a list of places that you can ask questions: ...@@ -42,7 +42,6 @@ by using public channels. Here is a list of places that you can ask questions:
* Ask on https://stackoverflow.com and tag your questions with ``python-bob``. * Ask on https://stackoverflow.com and tag your questions with ``python-bob``.
This is the preferred way. This is the preferred way.
* Ask on our mailing list: https://www.idiap.ch/software/bob/discuss
How to contribute How to contribute
......
...@@ -4,40 +4,44 @@ ...@@ -4,40 +4,44 @@
Installation instructions Installation instructions
=========================== ===========================
By now you should know that Bob is made of several :ref:`bob.packages`. There is no single By now you should know that Bob is made of several :ref:`bob.packages`. There is
package that installs all Bob packages because that would just take too much space. no single package that installs all Bob packages because that would just take
Follow the instruction below to install any Bob package. too much space. Follow the instruction below to install any Bob package.
We offer pre-compiled binary installations of Bob using `conda`_ for Linux and We offer pre-compiled binary installations of Bob using `conda`_ for Linux and
MacOS 64-bit operating systems. Follow the guide below to learn to install any Bob MacOS 64-bit operating systems. Follow the guide below to learn to install any
package. Bob does not work on Windows. Bob package. Bob does not work on Windows.
#. Install `mamba`_ (`mambaforge`_ is preferred) or `conda`_ (`miniforge`_ is
preferred) and get familiar with it. The instructions below use ``mamba``
because it's faster than ``conda``, but you may replace it by ``conda``.
#. Install `conda`_ (miniconda is preferred) and get familiar with it.
#. Make sure you have an up-to-date `conda`_ installation (conda 4.4 and above #. Make sure you have an up-to-date `conda`_ installation (conda 4.4 and above
is needed) with the **correct configuration** by running the commands is needed) with the **correct configuration** by running the commands below:
below:
.. code:: sh .. code:: sh
$ conda update -n base -c defaults conda # install mamba if you don't yet have it installed.
$ conda install -n base -c conda-forge mamba
$ mamba update -n base -c conda-forge conda mamba
$ conda config --set show_channel_urls True $ conda config --set show_channel_urls True
#. Create an environment with the specific Bob packages that you need. For example if #. Create an environment with the specific Bob packages that you need. For
you want to install ``bob.io.image`` and ``bob.bio.face``: example if you want to install ``bob.io.image`` and ``bob.bio.face``:
.. code:: sh .. code:: sh
$ conda create --name bob_env1 --override-channels \ $ mamba create --name bob_env1 --override-channels \
-c https://www.idiap.ch/software/bob/conda -c defaults \ -c https://www.idiap.ch/software/bob/conda -c conda-forge \
python=3 bob.io.image bob.bio.face python=3 bob.io.image bob.bio.face
#. Then activate the environment and configure its channels to make sure the channel #. Then activate the environment and configure its channels to make sure the
list is correct in the future as well: channel list is correct in the future as well:
.. code:: sh .. code:: sh
$ conda activate bob_env1 $ conda activate bob_env1
$ conda config --env --add channels defaults $ conda config --env --add channels conda-forge
$ conda config --env --add channels https://www.idiap.ch/software/bob/conda $ conda config --env --add channels https://www.idiap.ch/software/bob/conda
#. If you decide to install more packages in the future, just conda install them: #. If you decide to install more packages in the future, just conda install them:
...@@ -45,17 +49,17 @@ package. Bob does not work on Windows. ...@@ -45,17 +49,17 @@ package. Bob does not work on Windows.
.. code:: sh .. code:: sh
$ conda activate bob_env1 $ conda activate bob_env1
$ conda install bob.io.video bob.bio.video ... $ mamba install bob.io.video bob.bio.video ...
For a comprehensive list of packages that are either part of |project| or use For a comprehensive list of packages that are either part of |project| or use
|project|, please visit :ref:`bob.packages`. |project|, please visit :ref:`bob.packages`.
.. warning:: .. warning::
Be aware that if you use packages from our channel and other user/community Be aware that if you use packages from our channel and other channels
channels (especially ``conda-forge``) in one environment, you may end up (especially ``defaults``) in one environment, you may end up with a broken
with a broken envrionment. We can only guarantee that the packages in our envrionment. We can only guarantee that the packages in our channel are
channel are compatible with the ``defaults`` channel. compatible with the ``conda-forge`` channel.
.. note:: .. note::
...@@ -67,8 +71,9 @@ For a comprehensive list of packages that are either part of |project| or use ...@@ -67,8 +71,9 @@ For a comprehensive list of packages that are either part of |project| or use
.. note:: .. note::
Bob has been reported to run on arm processors (e.g. Raspberry Pi) but is Bob has been reported to run on arm processors (e.g. Raspberry Pi) but is
not installable with conda. Please see https://stackoverflow.com/questions/50803148 not installable with conda. Please see
for installations on how to install Bob from source. https://stackoverflow.com/questions/50803148 for installations on how to
install Bob from source.
.. _bob.source: .. _bob.source:
...@@ -76,18 +81,18 @@ For a comprehensive list of packages that are either part of |project| or use ...@@ -76,18 +81,18 @@ For a comprehensive list of packages that are either part of |project| or use
Developing Bob packages Developing Bob packages
======================= =======================
Use :ref:`bob.devtools <bob.devtools>` if you want to develop Bob packages or create Use :ref:`bob.devtools <bob.devtools>` if you want to develop Bob packages or
a new package. **DO NOT** modify (including adding extra files) the source code of Bob create a new package. **DO NOT** modify (including adding extra files) the
packages in your Conda environments. Typically, Bob packages can be extended without source code of Bob packages in your Conda environments. Typically, Bob packages
modifying the original package. So you may want to put your new code in a new package can be extended without modifying the original package. So you may want to put
instead of modifying the original package. your new code in a new package instead of modifying the original package.
.. warning:: .. warning::
Conda uses hard links to create new Conda uses hard links to create new environments from a cache folder. Editing
environments from a cache folder. Editing a file in one of the environments will edit a file in one of the environments will edit that file in **ALL** of your
that file in **ALL** of your environments. The only safe way to recover from this is to environments. The only safe way to recover from this is to delete your Conda
delete your Conda installation completely and installing everything again from scratch. installation completely and installing everything again from scratch.
Installing older versions of Bob Installing older versions of Bob
...@@ -98,19 +103,20 @@ using conda. For example: ...@@ -98,19 +103,20 @@ using conda. For example:
.. code:: sh .. code:: sh
$ conda install \ $ mamba install \
-c https://www.idiap.ch/software/bob/conda \ -c https://www.idiap.ch/software/bob/conda \
-c defaults \ -c defaults \
-c https://www.idiap.ch/software/bob/conda/label/archive \ -c https://www.idiap.ch/software/bob/conda/label/archive \
bob=4.0.0 bob.io.base bob=4.0.0 bob.io.base
will install the version of ``bob.io.base`` that was associated with the Bob will install the version of ``bob.io.base`` that was associated with the Bob
4.0.0 release. 4.0.0 release. Bob 9 and earlier used the ``defaults`` channel as base, for Bob
10 and later replace ``defaults`` with ``conda-forge``.
.. note:: .. note::
If you install the ``bob`` conda package, you may need to change your channel list If you install the ``bob`` conda package, you may need to change your
to: channel list to:
.. code:: sh .. code:: sh
...@@ -135,22 +141,21 @@ To install them, download one of the files above and run: ...@@ -135,22 +141,21 @@ To install them, download one of the files above and run:
.. code:: sh .. code:: sh
$ conda env create --file v300py36.yaml $ mamba env create --file v300py36.yaml
Details (advanced users) Details (advanced users)
======================== ========================
Since Bob 4, the ``bob`` conda package is just a meta package that pins all Since Bob 4, the ``bob`` conda package is just a meta package that pins all
packages to a specific version. Installing ``bob`` will not install anything; packages to a specific version. Installing ``bob`` will not install anything; it
it will just impose pinnings in your environment. Normally, installations of will just impose pinnings in your environment. Normally, installations of Bob
Bob packages should work without installing ``bob`` itself. For example, packages should work without installing ``bob`` itself. For example, running:
running:
.. code:: sh .. code:: sh
$ conda create --name env_name --override-channels \ $ mamba create --name env_name --override-channels \
-c https://www.idiap.ch/software/bob/conda -c defaults \ -c https://www.idiap.ch/software/bob/conda -c conda-forge \
bob.<package-name> bob.<package-name>
should always create a working environment. If it doesn't, please let us know. should always create a working environment. If it doesn't, please let us know.
......
...@@ -29,9 +29,12 @@ ...@@ -29,9 +29,12 @@
.. _libpng: http://libpng.org/pub/png/libpng.html .. _libpng: http://libpng.org/pub/png/libpng.html
.. _libtiff: http://www.remotesensing.org/libtiff/ .. _libtiff: http://www.remotesensing.org/libtiff/
.. _mailing list: https://www.idiap.ch/software/bob/discuss .. _mailing list: https://www.idiap.ch/software/bob/discuss
.. _mamba: https://github.com/mamba-org/mamba
.. _mambaforge: https://github.com/conda-forge/miniforge#mambaforge
.. _MatIO: http://matio.sourceforge.net .. _MatIO: http://matio.sourceforge.net
.. _Matplotlib: http://matplotlib.sourceforge.net .. _Matplotlib: http://matplotlib.sourceforge.net
.. _miniconda: http://conda.pydata.org/miniconda.html .. _miniconda: http://conda.pydata.org/miniconda.html
.. _miniforge: https://github.com/conda-forge/miniforge/#miniforge3
.. _MIT: http://www.opensource.org/licenses/MIT .. _MIT: http://www.opensource.org/licenses/MIT
.. _nose: http://nose.readthedocs.org .. _nose: http://nose.readthedocs.org
.. _NumPy Reference: https://docs.scipy.org/doc/numpy/ .. _NumPy Reference: https://docs.scipy.org/doc/numpy/
......
0% Loading or .
You are about to add 0 people to the discussion. Proceed with caution.
Please register or to comment