pytask.new: comparison parts/django/docs/topics/install.txt

equal deleted inserted replaced

-:5ff1fc726848
+:c6bca38c1cbf
+=====================
+How to install Django
+=====================
+This document will get you up and running with Django.
+Install Python
+==============
+Being a Python Web framework, Django requires Python.
+It works with any Python version from 2.4 to 2.7 (due to backwards
+incompatibilities in Python 3.0, Django does not currently work with
+Python 3.0; see :doc:`the Django FAQ </faq/install>` for more
+information on supported Python versions and the 3.0 transition).
+Get Python at http://www.python.org. If you're running Linux or Mac OS X, you
+probably already have it installed.
+.. admonition:: Django on Jython
+If you use Jython_ (a Python implementation for the Java platform), you'll
+need to follow a few additional steps. See :doc:`/howto/jython` for details.
+.. _jython: http://jython.org/
+Install Apache and mod_wsgi
+=============================
+If you just want to experiment with Django, skip ahead to the next section;
+Django includes a lightweight Web server you can use for testing, so you won't
+need to set up Apache until you're ready to deploy Django in production.
+If you want to use Django on a production site, use Apache with `mod_wsgi`_.
+mod_wsgi is similar to mod_perl -- it embeds Python within Apache and loads
+Python code into memory when the server starts. Code stays in memory throughout
+the life of an Apache process, which leads to significant performance gains over
+other server arrangements. Make sure you have Apache installed, with the
+mod_wsgi module activated. Django will work with any version of Apache that
+supports mod_wsgi.
+See :doc:`How to use Django with mod_wsgi </howto/deployment/modwsgi>` for
+information on how to configure mod_wsgi once you have it installed.
+If you can't use mod_wsgi for some reason, fear not: Django supports many other
+deployment options. A great second choice is :doc:`mod_python
+</howto/deployment/modpython>`, the predecessor to mod_wsgi. Additionally, Django
+follows the WSGI_ spec, which allows it to run on a variety of server platforms.
+See the `server-arrangements wiki page`_ for specific installation instructions
+for each platform.
+.. _Apache: http://httpd.apache.org/
+.. _mod_wsgi: http://code.google.com/p/modwsgi/
+.. _WSGI: http://www.python.org/dev/peps/pep-0333/
+.. _server-arrangements wiki page: http://code.djangoproject.com/wiki/ServerArrangements
+.. _database-installation:
+Get your database running
+=========================
+If you plan to use Django's database API functionality, you'll need to make
+sure a database server is running. Django supports many different database
+servers and is officially supported with PostgreSQL_, MySQL_, Oracle_ and
+SQLite_ (although SQLite doesn't require a separate server to be running).
+In addition to the officially supported databases, there are backends provided
+by 3rd parties that allow you to use other databases with Django:
+* `Sybase SQL Anywhere`_
+* `IBM DB2`_
+* `Microsoft SQL Server 2005`_
+* Firebird_
+* ODBC_
+The Django versions and ORM features supported by these unofficial backends
+vary considerably. Queries regarding the specific capabilities of these
+unofficial backends, along with any support queries, should be directed to the
+support channels provided by each 3rd party project.
+In addition to a database backend, you'll need to make sure your Python
+database bindings are installed.
+* If you're using PostgreSQL, you'll need the psycopg_ package. Django supports
+both version 1 and 2. (When you configure Django's database layer, specify
+either ``postgresql`` [for version 1] or ``postgresql_psycopg2`` [for version 2].)
+You might want to refer to our :ref:`PostgreSQL notes <postgresql-notes>` for
+further technical details specific to this database.
+If you're on Windows, check out the unofficial `compiled Windows version`_.
+* If you're using MySQL, you'll need MySQLdb_, version 1.2.1p2 or higher. You
+will also want to read the database-specific :ref:`notes for the MySQL
+backend <mysql-notes>`.
+* If you're using SQLite and Python 2.4, you'll need pysqlite_. Use version
+2.0.3 or higher. Python 2.5 ships with an SQLite wrapper in the standard
+library, so you don't need to install anything extra in that case. Please
+read the :ref:`SQLite backend notes <sqlite-notes>`.
+* If you're using Oracle, you'll need a copy of cx_Oracle_, but please
+read the database-specific :ref:`notes for the Oracle backend <oracle-notes>`
+for important information regarding supported versions of both Oracle and
+``cx_Oracle``.
+* If you're using an unofficial 3rd party backend, please consult the
+documentation provided for any additional requirements.
+If you plan to use Django's ``manage.py syncdb`` command to
+automatically create database tables for your models, you'll need to
+ensure that Django has permission to create and alter tables in the
+database you're using; if you plan to manually create the tables, you
+can simply grant Django ``SELECT``, ``INSERT``, ``UPDATE`` and
+``DELETE`` permissions. On some databases, Django will need
+``ALTER TABLE`` privileges during ``syncdb`` but won't issue
+``ALTER TABLE`` statements on a table once ``syncdb`` has created it.
+If you're using Django's :doc:`testing framework</topics/testing>` to test database queries,
+Django will need permission to create a test database.
+.. _PostgreSQL: http://www.postgresql.org/
+.. _MySQL: http://www.mysql.com/
+.. _psycopg: http://initd.org/pub/software/psycopg/
+.. _compiled Windows version: http://stickpeople.com/projects/python/win-psycopg/
+.. _MySQLdb: http://sourceforge.net/projects/mysql-python
+.. _SQLite: http://www.sqlite.org/
+.. _pysqlite: http://trac.edgewall.org/wiki/PySqlite
+.. _cx_Oracle: http://cx-oracle.sourceforge.net/
+.. _Oracle: http://www.oracle.com/
+.. _Sybase SQL Anywhere: http://code.google.com/p/sqlany-django/
+.. _IBM DB2: http://code.google.com/p/ibm-db/
+.. _Microsoft SQL Server 2005: http://code.google.com/p/django-mssql/
+.. _Firebird: http://code.google.com/p/django-firebird/
+.. _ODBC: http://code.google.com/p/django-pyodbc/
+.. _removing-old-versions-of-django:
+Remove any old versions of Django
+=================================
+If you are upgrading your installation of Django from a previous version,
+you will need to uninstall the old Django version before installing the
+new version.
+If you installed Django using ``setup.py install``, uninstalling
+is as simple as deleting the ``django`` directory from your Python
+``site-packages``.
+If you installed Django from a Python egg, remove the Django ``.egg`` file,
+and remove the reference to the egg in the file named ``easy-install.pth``.
+This file should also be located in your ``site-packages`` directory.
+.. admonition:: Where are my ``site-packages`` stored?
+The location of the ``site-packages`` directory depends on the operating
+system, and the location in which Python was installed. To find out your
+system's ``site-packages`` location, execute the following:
+.. code-block:: bash
+python -c "from distutils.sysconfig import get_python_lib; print get_python_lib()"
+(Note that this should be run from a shell prompt, not a Python interactive
+prompt.)
+.. _install-django-code:
+Install the Django code
+=======================
+Installation instructions are slightly different depending on whether you're
+installing a distribution-specific package, downloading the latest official
+release, or fetching the latest development version.
+It's easy, no matter which way you choose.
+Installing a distribution-specific package
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Check the :doc:`distribution specific notes </misc/distributions>` to see if your
+platform/distribution provides official Django packages/installers.
+Distribution-provided packages will typically allow for automatic installation
+of dependencies and easy upgrade paths.
+.. _installing-official-release:
+Installing an official release
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+1. Download the latest release from our `download page`_.
+2. Untar the downloaded file (e.g. ``tar xzvf Django-NNN.tar.gz``,
+where ``NNN`` is the version number of the latest release).
+If you're using Windows, you can download the command-line tool
+bsdtar_ to do this, or you can use a GUI-based tool such as 7-zip_.
+3. Change into the directory created in step 2 (e.g. ``cd Django-NNN``).
+4. If you're using Linux, Mac OS X or some other flavor of Unix, enter
+the command ``sudo python setup.py install`` at the shell prompt.
+If you're using Windows, start up a command shell with administrator
+privileges and run the command ``setup.py install``.
+These commands will install Django in your Python installation's
+``site-packages`` directory.
+.. _bsdtar: http://gnuwin32.sourceforge.net/packages/bsdtar.htm
+.. _7-zip: http://www.7-zip.org/
+.. _installing-development-version:
+Installing the development version
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+.. admonition:: Tracking Django development
+If you decide to use the latest development version of Django,
+you'll want to pay close attention to `the development timeline`_,
+and you'll want to keep an eye on `the list of
+backwards-incompatible changes`_. This will help you stay on top
+of any new features you might want to use, as well as any changes
+you'll need to make to your code when updating your copy of Django.
+(For stable releases, any necessary changes are documented in the
+release notes.)
+.. _the development timeline: http://code.djangoproject.com/timeline
+.. _the list of backwards-incompatible changes: http://code.djangoproject.com/wiki/BackwardsIncompatibleChanges
+If you'd like to be able to update your Django code occasionally with the
+latest bug fixes and improvements, follow these instructions:
+1. Make sure that you have Subversion_ installed, and that you can run its
+commands from a shell. (Enter ``svn help`` at a shell prompt to test
+this.)
+2. Check out Django's main development branch (the 'trunk') like so:
+.. code-block:: bash
+svn co http://code.djangoproject.com/svn/django/trunk/ django-trunk
+3. Next, make sure that the Python interpreter can load Django's code. There
+are various ways of accomplishing this.  One of the most convenient, on
+Linux, Mac OSX or other Unix-like systems, is to use a symbolic link:
+.. code-block:: bash
+ln -s WORKING-DIR/django-trunk/django SITE-PACKAGES-DIR/django
+(In the above line, change ``SITE-PACKAGES-DIR`` to match the location of
+your system's ``site-packages`` directory, as explained in the
+"Where are my ``site-packages`` stored?" section above. Change WORKING-DIR
+to match the full path to your new ``django-trunk`` directory.)
+Alternatively, you can define your ``PYTHONPATH`` environment variable
+so that it includes the ``django-trunk`` directory. This is perhaps the
+most convenient solution on Windows systems, which don't support symbolic
+links. (Environment variables can be defined on Windows systems `from the
+Control Panel`_.)
+.. admonition:: What about Apache and mod_python?
+If you take the approach of setting ``PYTHONPATH``, you'll need to
+remember to do the same thing in your Apache configuration once you
+deploy your production site. Do this by setting ``PythonPath`` in your
+Apache configuration file.
+More information about deployment is available, of course, in our
+:doc:`How to use Django with mod_python </howto/deployment/modpython>`
+documentation.
+4. On Unix-like systems, create a symbolic link to the file
+``django-trunk/django/bin/django-admin.py`` in a directory on your system
+path, such as ``/usr/local/bin``. For example:
+.. code-block:: bash
+ln -s WORKING-DIR/django-trunk/django/bin/django-admin.py /usr/local/bin
+(In the above line, change WORKING-DIR to match the full path to your new
+``django-trunk`` directory.)
+This simply lets you type ``django-admin.py`` from within any directory,
+rather than having to qualify the command with the full path to the file.
+On Windows systems, the same result can be achieved by copying the file
+``django-trunk/django/bin/django-admin.py`` to somewhere on your system
+path, for example ``C:\Python24\Scripts``.
+You *don't* have to run ``python setup.py install``, because you've already
+carried out the equivalent actions in steps 3 and 4.
+When you want to update your copy of the Django source code, just run the
+command ``svn update`` from within the ``django-trunk`` directory. When you do
+this, Subversion will automatically download any changes.
+.. _`download page`: http://www.djangoproject.com/download/
+.. _Subversion: http://subversion.tigris.org/
+.. _from the Control Panel: http://www.microsoft.com/resources/documentation/windows/xp/all/proddocs/en-us/sysdm_advancd_environmnt_addchange_variable.mspx