.. _develop:
Development
===========
* `Source code `_
* `Report an issue `_
.. _developer-install:
Installing the development version
----------------------------------
To use the most recent IgDiscover version from Git, follow these steps.
1. If you haven’t done so, install miniconda. See the first steps of the
:ref:`regular installation instructions `. Do not install
IgDiscover, yet!
2. Clone the IgDiscover repository::
git clone https://github.com/NBISweden/IgDiscover.git
(Use the git@ URL instead if you are a developer.)
4. Create a new Conda environment using the ``environment.yml`` file in the
repository::
cd IgDiscover
conda env create -n igdiscover -f environment.yml
You can choose a different environment name by changing the name after the
``-n`` parameter. This may be necessary, when you already have a regular
(non-developer) IgDiscover installation in an ``igdiscover`` environment
that you don’t want to overwrite.
5. Activate the environment::
source activate igdiscover
(Or use whichever name you chose above.)
6. Install IgDiscover in “editable” mode::
python3 -m pip install -e .
Whenever you want to update the software::
cd IgDiscover
git pull
It may also be necessary to repeat the ``python3 -m pip install -e .`` step.
IgBLAST result cache
--------------------
For development, in particular when running tests repeatedly, you should enable the IgBLAST
result cache. The cache stores IgBLAST output. If the same dataset with the same dataset is run
a second time, the result is retrieved from the cache and IgBLAST is not re-run. This saves a lot
of time when re-running datasets, but may also fill up the cache directory ``~/.cache/igdiscover/``.
Also, in production, datasets are usually not re-run with the same settings, which is why
caching is disabled by default.
To enable the cache, create a file ``~/.config/igdiscover.conf`` with the following content::
use_cache: true
The file is in YAML format, but at the moment, no other settings are supported.
Building the documentation
--------------------------
Go to the ``doc/`` directory in the repository, then run::
make
to build the documentation locally. Open ``_build/html/index.html`` in
a browser. The layout is different from the `version shown on
Read the Docs `_, but allows you to
preview any changes you may have made.
Making a release
----------------
We use `setuptools_scm `_ to
manage version numbers. It extracts the version number from the
most recent tag in Git. Thus, to increment the version number, create
a Git tag::
git tag v0.5
The ``v`` prefix is mandatory.
Then:
* Run ``pytest``
* Push the tag: ``git push --tags``
* The GitHub workflow will create a new build and deploy it to PyPI
* Wait for the BiocondaBot to create a bump PR; adjust the dependencies if needed
.. _removing-igdiscover:
Removing IgDiscover from a Linux system
---------------------------------------
If you have been playing around with different installation methods (``pip``,
``conda``, ``git``, ``python3 setup.py install`` etc.) you may have multiple
copies of IgDiscover on your system and you will likely run into problems
on updates. Here is a list you can follow in order to get rid of the
installations as preparation for a clean re-install. *Do not* add ``sudo`` to
the commands below if you get permission problems, unless explicitly told to do
so! If one of the steps does not work, that is fine, just continue.
1. Delete miniconda: Run the command ``which conda``. The output will be
something like ``/home/myusername/miniconda3/bin/conda``. The part before
``bin/conda`` is the miniconda installation directory. Delete that folder. In
this case, you would need to delete ``miniconda3`` in ``/home/myusername``.
2. Run ``pip3 uninstall igdiscover``. If this runs successfully and prints some
messages about removing files, then *repeat the same command*! Do this
until you get a message telling you that the package cannot be uninstalled
because it is not installed.
3. Repeat the previous step, but with ``pip3 uninstall sqt``.
4. If you have a directory named ``.local`` within your home directory, you may
want to rename it: ``mv .local dot-local-backup`` You can also delete it, but
there is a small risk that other software (not IgDiscover) uses that
directory. The directory is hidden, so a normal ``ls`` will not show it.
Use ``ls -la`` while in your home directory to see it.
5. If you have ever used ``sudo`` to install IgDiscover, you may have an
installation in ``/usr/local/``. You can try to remove it with
``sudo pip3 uninstall igdiscover``.
6. Delete the cloned Git repository if you have one. This is the directory in
which you run ``git pull``.
Finally, you can follow the normal installation instructions and then the
developer installation instructions.