.. _linking:

Installing links to local projects
----------------------------------

.. index::
   single: Local projects; installing links
   single: Editable; installations

Sometimes developers want to have a project that's being worked on available
in an environment as if it was installed there, but without actually installing
it because they want any changes they make to the project to be immediately
reflected in the environment without the need to reinstall. (``pip`` calls
these *editable* installations.)

You can get the equivalent effect using the ``distil link`` command, which
works like ``distil install`` but only writes a link to the target
environment (see :ref:`install-locations` to see where links are installed).

The command is run like this::

    $ distil -e e2 link /path/to/my/project

You can specify more than one project path. Projects to be linked need to have
a ``package.json`` file in the project directory, so that the project name can
be determined. Here's an example::

    $ e2/bin/python -c "import sarge; print(sarge.__file__)"
    Traceback (most recent call last):
      File "<string>", line 1, in <module>
    ImportError: No module named sarge

There's no ``sarge`` project available in the environment. Let's download it
to a local directory::

    $ distil download -d /tmp sarge
    Downloading https://pypi.python.org/packages/source/s/sarge/sarge-0.1.tar.gz to /tmp/sarge-0.1
        35KB @ 210 KB/s 100 % Done: 00:00:00
    Unpacking ... done.

Now let's link the project::

    $ distil -e e2 link /tmp/sarge-0.1

The command doesn't output anything unless an error occurs. Now, ``sarge``
should be available in the environment::

    $ e2/bin/python -c "import sarge; print(sarge.__file__)"
    /tmp/sarge-0.1/sarge/__init__.py

As you can see, the ``sarge`` project available in the environment is the one
in the editable location ``/tmp/sarge-0.1``.

Removing links
~~~~~~~~~~~~~~

To remove links, you specify ``-r`` and the names of the projects you want to
remove links to::

    $ distil -e e2 link -r sarge

The command doesn't output anything unless an error occurs. Now, ``sarge``
will no longer be available in the environment::

    $ e2/bin/python -c "import sarge; print(sarge.__file__)"
    Traceback (most recent call last):
      File "<string>", line 1, in <module>
    ImportError: No module named sarge

Here is the complete help for ``distil``'s ``link`` command::

    $ distil help link
    usage: distil link [-h] [-r] [-s] DIR_OR_NAME [DIR_OR_NAME ...]

    Install links to one or more local projects so that they can be used while
    remaining editable.

    positional arguments:
      DIR_OR_NAME   A directory of a local project when linking, or the project
                    name when unlinking.

    optional arguments:
      -h, --help    show this help message and exit
      -r            Remove links to named projects.
      -s, --system  Install to system Python (may require sufficient privileges).
                    By default, installations are written to the user site
                    (~/.local), or to a virtual environment specified with -e.