Permalink
Browse files

Added local vendor library to facilitate upgrades of playdoh-lib. Iss…

…ue 19.
  • Loading branch information...
1 parent 88755f7 commit 8bde7907fe8d715b1f0fa6c9f5293eb724d4e900 @fwenzel fwenzel committed Mar 1, 2011
Showing with 66 additions and 35 deletions.
  1. +59 −35 docs/packages.rst
  2. +7 −0 manage.py
  3. 0 vendor-local/vendor.pth
View
@@ -6,9 +6,15 @@ pip and friends: Packaging
*(largely borrowed from Zamboni)*
-There are two ways of getting packages in your playdoh-based project. The
-first is to install everything using pip. We have our packages separated into
-three files:
+There are two ways of getting packages in your playdoh-based project. ``pip``
+and ``virtualenv`` as well as the preferred method, a **vendor library**.
+
+
+For reference: pip
+------------------
+
+The classical method of installing is using pip. We have our packages
+separated into three files:
:src:`requirements/compiled.txt`
All packages that require (or go faster with) compilation. These can't be
@@ -24,18 +30,15 @@ three files:
automatically includes ``requirements/prod.txt``.
-Installing through pip
-----------------------
-
-You can get a development environment with ::
+With pip, you can get a development environment with::
pip install -r requirements/dev.txt -r requirements/compiled.txt
-Using the vendor library
-------------------------
+Preferred: The vendor library
+-----------------------------
-The other method is to use the /vendor library of all packages and
+The other method is to use the ``/vendor`` library of all packages and
repositories.
By default, the vendor lib is checked out as a *git submodule* under
@@ -45,38 +48,36 @@ By default, the vendor lib is checked out as a *git submodule* under
Once the playdoh-lib repo has been downloaded to ``/vendor``, you only need to
install the compiled packages. These can come from your system package manager
-or from ::
+or from::
pip install -r requirements/compiled.txt
-Adding new packages
--------------------
-
-The vendor repo was seeded with ::
+Global vs. local library
+------------------------
- pip install -I --install-option="--home=`pwd`/vendor" --src='vendor/src' -r requirements/dev.txt
+playdoh provides a its default library in the ``vendor/`` directory. You *may*
+fork and change it, but that will make it hard to pull updates from the
+upstream library later.
- # ..delete some junk from vendor/lib/python...
+If you want to make only a few local additions or override some of the libs in
+``vendor/``, make those changes to the directory ``vendor-local/`` instead,
+which (in ``manage.py``) is given precedence over playdoh's vendor dir.
- # Create the .pth file so Python can find our src libs.
- find src -type d -depth 1 >> zamboni.pth
+All other instructions are equal.
- # Add all the submodules.
- for f in src/*; do
- pushd $f >/dev/null && REPO=$(git config remote.origin.url) && popd > /dev/null && git submodule add $REPO $f
- done
- git add .
+Adding new packages
+-------------------
-If we wanted to add a new dependency called ``cheeseballs`` to zamboni, you
-would add it to ``requirements/prod.txt`` or ``requirements/dev.txt``. This makes it available to
-users installing into virtualenvs.
+If we wanted to add a new dependency called ``cheeseballs`` to playdoh, you
+would add it to ``requirements/prod.txt`` or ``requirements/dev.txt``. This
+makes it available to users installing into virtualenvs.
We also need to add the new package to the vendor lib.
-First, you then need to update ``vendor/vendor.pth``. Python
-uses ``.pth`` files to dynamically add directories to ``sys.path`` (`docs
+First, you then need to update ``vendor-local/vendor.pth``. Python uses
+``.pth`` files to dynamically add directories to ``sys.path`` (`docs
<http://docs.python.org/library/site.html>`_).
I created ``vendor.pth`` with this::
@@ -88,14 +89,14 @@ this project is hosted:
For non-git based repos (hg, CVS, tarball) do::
- pip install -I --install-option="--home=`pwd`/vendor" --src='vendor/src' cheeseballs
- cd vendor
+ pip install -I --install-option="--home=`pwd`/vendor-local" --src='vendor-local/src' cheeseballs
+ cd vendor-local
git add src/cheeseballs
git commit vendor.pth src/cheeseballs
For a git-based package, add it as a git submodule::
- cd vendor
+ cd vendor-local
git submodule add git://github.com/mozilla/cheeseballs.git src/cheeseballs
git commit vendor.pth .gitmodules src/cheeseballs
@@ -105,12 +106,35 @@ So they need to be sourced with ``src/html5lib/src``, for example. Hopefully
you won't hit any snags like that.
+Advanced Topics
+---------------
+
+Initial creation of the vendor library
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The vendor repo was seeded with ::
+
+ pip install -I --install-option="--home=`pwd`/vendor" --src='vendor/src' -r requirements/dev.txt
+
+ # ..delete some junk from vendor/lib/python...
+
+ # Create the .pth file so Python can find our src libs.
+ find src -type d -depth 1 >> zamboni.pth
+
+ # Add all the submodules.
+ for f in src/*; do
+ pushd $f >/dev/null && REPO=$(git config remote.origin.url) && popd > /dev/null && git submodule add $REPO $f
+ done
+ git add .
+
+
Adding lots of git submodules
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-As noted in Adding new packages, you want to make your git-based packages *git submodules* inside the vendor
-library. To set up the first batch of submodules, something like the following
-happened::
+As noted in *Adding new packages*, git-based packages are *git submodules*
+inside the vendor library. To set up the first batch of submodules, something
+like the following happened::
for f in src/*
pushd $f && REPO=$(git config remote.origin.url) && popd && git submodule add $REPO $f
+
View
@@ -12,9 +12,16 @@
site.addsitedir(path('apps'))
site.addsitedir(path('lib'))
+
+# Global (upstream) vendor library
site.addsitedir(path('vendor'))
site.addsitedir(path('vendor/lib/python'))
+# Local (project) vendor library
+site.addsitedir(path('vendor'))
+site.addsitedir(path('vendor/lib/python'))
+
+
# Move the new items to the front of sys.path. (via virtualenv)
new_sys_path = []
for item in list(sys.path):
View
No changes.

0 comments on commit 8bde790

Please sign in to comment.