aboutsummaryrefslogtreecommitdiffstats
path: root/keystone-moon/doc/source/devref
diff options
context:
space:
mode:
Diffstat (limited to 'keystone-moon/doc/source/devref')
-rw-r--r--keystone-moon/doc/source/devref/development.environment.rst175
1 files changed, 175 insertions, 0 deletions
diff --git a/keystone-moon/doc/source/devref/development.environment.rst b/keystone-moon/doc/source/devref/development.environment.rst
new file mode 100644
index 00000000..2718966a
--- /dev/null
+++ b/keystone-moon/doc/source/devref/development.environment.rst
@@ -0,0 +1,175 @@
+..
+ Copyright 2011-2012 OpenStack Foundation
+ All Rights Reserved.
+
+ Licensed under the Apache License, Version 2.0 (the "License"); you may
+ not use this file except in compliance with the License. You may obtain
+ a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+ WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+ License for the specific language governing permissions and limitations
+ under the License.
+
+=============================================
+Setting up a Keystone development environment
+=============================================
+
+This document describes getting the source from keystone's `Git repository`_
+for development purposes.
+
+To install Keystone from packaging, refer instead to Keystone's `User
+Documentation`_.
+
+.. _`Git Repository`: http://git.openstack.org/cgit/openstack/keystone
+.. _`User Documentation`: http://docs.openstack.org/
+
+Prerequisites
+=============
+
+This document assumes you are using Ubuntu, Fedora or openSUSE (SLE)
+
+And that you have the following tools available on your system:
+
+- Python_ 2.7 and 3.4
+- git_
+- setuptools_
+- pip_
+- msgfmt (part of the gettext package)
+- virtualenv_
+- tox_
+
+**Reminder**: If you're successfully using a different platform, or a
+different version of the above, please document your configuration here!
+
+.. _Python: http://www.python.org/
+.. _git: http://git-scm.com/
+.. _setuptools: http://pypi.python.org/pypi/setuptools
+.. _tox: https://pypi.python.org/pypi/tox
+
+Getting the latest code
+=======================
+
+Make a clone of the code from our `Git repository`:
+
+.. code-block:: bash
+
+ $ git clone https://git.openstack.org/openstack/keystone.git
+
+When that is complete, you can:
+
+.. code-block:: bash
+
+ $ cd keystone
+
+Installing dependencies
+=======================
+
+Keystone maintains two lists of dependencies::
+
+ requirements.txt
+ test-requirements.txt
+
+The first is the list of dependencies needed for running keystone, the second list includes dependencies used for active development and testing of Keystone itself.
+
+These dependencies can be installed from PyPi_ using the Python tool pip_.
+
+.. _PyPi: http://pypi.python.org/
+.. _pip: http://pypi.python.org/pypi/pip
+
+However, your system *may* need additional dependencies that `pip` (and by
+extension, PyPi) cannot satisfy. These dependencies should be installed
+prior to using `pip`, and the installation method may vary depending on
+your platform.
+
+Ubuntu 14.04, 15.10:
+
+.. code-block:: bash
+
+ $ sudo apt-get install python-dev python3-dev libxml2-dev libxslt1-dev \
+ libsasl2-dev libsqlite3-dev libssl-dev libldap2-dev libffi-dev
+
+
+Fedora 19+:
+
+.. code-block:: bash
+
+ $ sudo yum install python-lxml python-greenlet-devel python-ldap \
+ sqlite-devel openldap-devel python-devel libxslt-devel \
+ openssl-devel libffi-devel
+
+openSUSE 13.2 (SLE 12):
+
+.. code-block:: bash
+
+ $ sudo zypper install libxslt-devel openldap2-devel libopenssl-devel \
+ python-devel python-greenlet-devel python-ldap python-lxml \
+ python-pysqlite sqlite3-devel
+
+PyPi Packages and VirtualEnv
+----------------------------
+
+We recommend establishing a virtualenv to run Keystone within. virtualenv
+limits the Python environment to just what you're installing as dependencies,
+useful to keep a clean environment for working on Keystone.
+
+.. code-block:: bash
+
+ $ tox -e venv --notest
+
+This will create a local virtual environment in the directory ``.tox``.
+Once created, you can activate this virtualenv for your current shell using:
+
+.. code-block:: bash
+
+ $ source .tox/venv/bin/activate
+
+The virtual environment can be disabled using the command:
+
+.. code-block:: bash
+
+ $ deactivate
+
+You can also use ``tox -e venv`` to prefix commands so that they run
+within the virtual environment. For more information on virtual environments,
+see virtualenv_.
+
+.. _virtualenv: http://www.virtualenv.org/
+
+If you want to run Keystone outside of a virtualenv, you can install the
+dependencies directly into your system from the requirements files:
+
+.. code-block:: bash
+
+ # Install the dependencies for running keystone
+ $ pip install -r requirements.txt
+
+ # Install the dependencies for developing, testing, and running keystone
+ $ pip install -r test-requirements.txt
+
+ # Use 'python setup.py' to link Keystone into Python's site-packages
+ $ python setup.py develop
+
+
+Verifying Keystone is set up
+============================
+
+Once set up, either directly or within a virtualenv, you should be able to
+invoke Python and import the libraries. If you're using a virtualenv, don't
+forget to activate it:
+
+.. code-block:: bash
+
+ $ source .tox/venv/bin/activate
+
+You should then be able to `import keystone` using Python without issue:
+
+.. code-block:: bash
+
+ $ python -c "import keystone"
+
+If you can import Keystone without a traceback, you should be ready to move on
+to :doc:`../developing`.