Skip to content

Latest commit

 

History

History
125 lines (82 loc) · 3.36 KB

vendor.rst

File metadata and controls

125 lines (82 loc) · 3.36 KB

Vendor Library

The vendor library is the easiest way to manage pure-Python dependencies. It contains the source code for all the library Kitsune depends on.

Getting the Vendor Library

Getting the vendor library is easy. In your Kitsune clone, just type:

$ git clone --recursive git://github.com/jsocol/kitsune-lib.git vendor

Git will clone the repository and all its submodules.

Updating the Vendor Library

From time to time we need to update libraries, either for new versions of libraries or to add a new library. There are two ways to do that. The easiest and prefered way is pure git.

Using Git Submodules

Using git submodules is prefered because it is much easier to maintain, and it keeps the repository size small. Upgrading is as simple as updating a submodule.

Updating a Library with Git Submodules

If the library is in vendor/src, it was pulled directly from version control, and if that version control was git, updating the submodule is as easy as:

$ cd vendor/src/$LIBRARY
$ git fetch origin
$ git checkout <REFSPEC>
$ cd ../..
$ git add vendor/src/$LIBRARY
$ git ci -m "Updating $LIBRARY"

Easy! Just like updating any other git submodule.

Adding a New Library with Git Submodules

Technically this can be done with pip install --no-install but there's an even easier method when installing a new library from a git repo:

$ cd vendor/src
$ git clone git://<repo>
$ cd ../..
$ ./addsubmodules.sh
$ vim kitsune.pth  # Add the new library's path
$ git add kitsune.pth
$ git ci -m "Adding $LIBRARY"

Using PyPI

Sometimes a library isn't in a git repository. It, sadly, happens. Maybe you can find a git mirror? If not, it might as well be installed from PyPI.

Updating a Library from PyPI

The easiest way to update a library from PyPI is to remove it completely and then install the new version.

$ cd vendor/packages
$ git rm -r $LIBRARY
$ cd ..
$ git ci -m "Removing version $VERSION of $LIBRARY"
$ cd ..

After removing the old version, go ahead and install the new one:

$ pip install --no-install --build=vendor/packages --src=vendor/src -I $LIBRARY

Finally, add the new library to git:

$ cd vendor
$ git add packages
$ git ci -m "Adding version $VERSION of $LIBRARY"

Caveat developer! Sometimes a library has dependencies that are already installed in the vendor repo. You may need to remove several of them to make everything work easily.

Adding a Library from PyPI

Adding a new library from PyPI is easy using pip:

$ pip install --no-install --build=vendor/packages --src=vendor/src -I $LIBRARY
$ cd vendor
$ git add packages
$ vim kitsune.pth  # Add any new libraries' paths.
$ git ci -m "Adding $LIBRARY"

Make sure you add any dependencies from the new library, as well.

Requirements Files

We still maintain requirements files in requirements/. Sometimes people will use these to install the requirements in a virtual environment. When you update the vendor repo, you should make sure to update version numbers (if necessary) in the requirements files.