@@ -12,132 +12,71 @@ Tools implemented in `bob.devtools` helps automate this process for |project| pa
...
@@ -12,132 +12,71 @@ Tools implemented in `bob.devtools` helps automate this process for |project| pa
TLDR
TLDR
====
====
Suppose you want to create a new package and at the same time develop two existing packages, ``bob.extension`` and ``bob.blitz``,
Suppose you want to checkout the package ``bob.blitz`` from source and start developing it locally. We will use the tools implemented in ``bob.devtools`` to create a proper developing environment to build and develop ``bob.blitz``. We assume you have ``bob.devtools`` installed on a conda environment named ``bdt`` (Refer to :ref:`bob.devtools.install` for detailed information.)
* Optionally add the packages you want to have in your local installation but not developing them to `eggs` in the `buildout.cfg` file and the `requirements/host` section of the `conda/meta.yaml` file.
* Create an isolated environment for your project.
* Create a proper conda environment:
.. code-block:: sh
.. code-block:: sh
$ bdt create --stable -vv awesome-project
$ cd bob.blitz
$ source activate awesome-project
$ conda activate bdt
$ bdt create -vv dev
$ conda deactivate
$ conda activate dev
* Install dependencies for `bob.extension` and `bob.blitz` using `conda install` command. You can find out the required dependencies by looking at `conda/meta.yaml` file for each package.
.. * Install dependencies for `bob.extension` and `bob.blitz` using `conda install` command. You can find out the required dependencies by looking at `conda/meta.yaml` file for each package.
# or with private docs also available at Idiap. Ask for its path from colleagues.
Sometimes when you are calling a function not interactively it is not acting normally. In that case import pkg_resources before importing your package. It is a known issue and we are working on it.
Sometimes when you are calling a function not interactively it is not acting normally. In that case import ``pkg_resources`` before importing your package. It is a known issue and we are working on it.
.. code-block:: sh
.. code-block:: sh
...
@@ -146,16 +85,15 @@ Optionally:
...
@@ -146,16 +85,15 @@ Optionally:
.. bob.devtools.local_development:
.. bob.devtools.local_development:
<<<<<<< HEAD
Local development of existing packages
Local development of existing packages
======================================
======================================
To develop existing |project| packages you need to checkout their source code and create a proper development environment using `buildout`.
To develop existing |project| packages you need to checkout their source code and create a proper development environment using `buildout`.
Checking out |project| package sources
Checking out package sources
--------------------------------------
----------------------------
|project| packages are developed through gitlab_. Various packages exist
|project| packages are developed through gitlab_. Various packages exist
in |project|'s gitlab_ instance. Here as an example we assume you want to install and build locally the `bob.blitz` pakcage. In order to checkout a package, just use git_:
in |project|'s gitlab_ instance. In the following we assume you want to install and build locally the ``bob.blitz`` package. In order to checkout a package, just use git_:
.. code-block:: sh
.. code-block:: sh
...
@@ -166,8 +104,8 @@ in |project|'s gitlab_ instance. Here as an example we assume you want to instal
...
@@ -166,8 +104,8 @@ in |project|'s gitlab_ instance. Here as an example we assume you want to instal
Create an isolated conda environment
Create an isolated conda environment
------------------------------------
------------------------------------
Now that we have the package checked out we need an isolated environment with proper configuration to develop the package. `bob.devtools` provides a tool that automatically creates such environment.
Now that we have the package checked out we need an isolated environment with proper configuration to develop the package. ``bob.devtools`` provides a tool that automatically creates such environment.
Before proceeding, you need to make sure that you already have a conda_ environment that has `bob.devtools` installed in. Refer to :ref:`bob.devtools.install` for installation information. Here we assume that you have a conda environment named `bdt` with installed `bob.devtools`.
Before proceeding, you need to make sure that you already have a conda_ environment with ``bob.devtools`` installed in it (Refer to :ref:`bob.devtools.install` for more information). let's assume that you have a conda environment named ``bdt`` with installed ``bob.devtools``.
.. code-block:: sh
.. code-block:: sh
...
@@ -180,7 +118,7 @@ Before proceeding, you need to make sure that you already have a conda_ environm
...
@@ -180,7 +118,7 @@ Before proceeding, you need to make sure that you already have a conda_ environm
Now you have an isolated conda environment named `dev` with proper channels set. For more information about conda channels refer to `conda channel documentation`_.
Now you have an isolated conda environment named `dev` with proper channels set. For more information about conda channels refer to `conda channel documentation`_.
The `bdt create` command assumes a directory named `conda' exists on the current directory and that it contains a file called `meta.yaml` containing the recipe for the package you want to create a development environment for.
The `bdt create` command assumes a directory named `conda`, exists on the current directory. The `conda` directory contains a file named `meta.yaml`, that is the recipe required to create a development environment for the package you want to develop.
.. note::
.. note::
...
@@ -263,7 +201,7 @@ or build the documentation:
...
@@ -263,7 +201,7 @@ or build the documentation:
.. note::
.. note::
`buildout` by default uses the file `buildout.cfg` but you can specify another file by using -c option. In fact for developing packages especially it they need to be developed along with other packages, another file, namely `develop.cfg` is used like following:
`buildout` by default uses the file `buildout.cfg` but you can specify another file by using -c option. In fact for developing packages especially if they need to be developed along with other packages, another file, namely `develop.cfg` is used like following:
.. code-block:: sh
.. code-block:: sh
...
@@ -305,9 +243,9 @@ Furthermore, you will be able to create distributable environments for each
...
@@ -305,9 +243,9 @@ Furthermore, you will be able to create distributable environments for each
project you have. This is a great way to release code for laboratory exercises
project you have. This is a great way to release code for laboratory exercises
or for a particular publication that depends on |project|.
or for a particular publication that depends on |project|.
It so happens that you want to develop several packages against each other for your project. Let's assume you want to develop package A and B simultaneously. We assume that package A is dependent on B. First we checkout package A and build an isolated conda environment as explained in the previous section. Then edit `buildout.cfg` file (or `develop.cfg`) and add package B to it as following:
It so happens that you want to develop several packages against each other for your project. Let's assume you want to develop ``bob.blitz`` and ``bob.extension`` simultaneously. ``bob.blitz`` is dependent on ``bob.devtools``. First we checkout package ``bob.blitz`` and build an isolated conda environment as explained in the previous section. Then edit `buildout.cfg` file (or `develop.cfg`) and add ``bob.extension`` to it as following: