[[PageOutline(2-5,Contents,pullout)]]

= Developer setup for Trac

== Installing the development tools

Before we begin to develop in Trac, or even download Trac code, create a standalone environment.

=== Create a working directory

Create a projects or working directory for your development efforts. So for example on some systems, you might have:
{{{
/Users/myname/projects
}}}

On Windows you would have:
{{{
C:\projects
}}}

'''Note:''' Don't create a directory called 'trac' yet. That comes later.

=== Get Subversion

This tutorial assumes you have Subversion (SVN) installed. If not, go to the [http://subversion.apache.org/ Subversion] website and follow the directions of installation there.

=== Get Python

On Linux, it is in most cases best to install Python using the package manager for your distribution. For example, on a distribution utilizing the Apt package manager (Debian, Ubuntu):
{{{#!sh
sudo apt-get install python2.6
}}}

You will also need some additional libraries:
{{{#!sh
sudo apt-get install python-subversion
}}}

On Windows, some of the available options are:
 * The official Python distribution from [http://www.python.org/download/ python.org].
 * The commercial [http://www.activestate.com/activepython/ ActivePython] from ActiveState.

Mac OS X 10.5 and later has Python >= 2.5 pre-installed.

=== Get easy_install

You will have `easy_install` if you have "setuptools" installed. Just make sure its version is >= 0.6c10. Previous versions do not work correctly with SVN 1.6.

Otherwise go to [http://peak.telecommunity.com/DevCenter/EasyInstall#installing-easy-install installing-easy-install] and follow the instructions there. However, most of the time you just take the text at [http://peak.telecommunity.com/dist/ez_setup.py ez_setup.py]. For Python 2.4 and 2.5 read Section [https://pypi.python.org/pypi/setuptools#python-2-4-and-python-2-5-support Python 2.4 and Python 2.5 support], save it as `ez_setup.py` on your hard drive, then from the command-line prompt type:
{{{#!sh
python ez_setup.py
}}}

To test if the installation was successful:
{{{#!sh
easy_install --help
}}}

=== Get virtualenv

From the command-line prompt type:
{{{#!sh
python -m easy_install virtualenv
}}}

On Linux you may need to prepend `python` with `sudo`.

=== Set up a virtual environment

From the command-line prompt type:
{{{#!sh
virtualenv trac
cd trac
source bin/activate
}}}

or for Windows:
{{{
python -m virtualenv trac
cd trac
cmd /k Scripts\activate.bat
}}}

If you have Trac installed in `/usr/lib` or `/usr/local/lib`, run the above virtualenv command with `--no-site-packages`.

You'll see your command-line prompt has changed. That means your environment is ready for Trac.

=== Upgrade Setuptools

Just to be sure you have a recent enough version of setuptools, and if not, you should upgrade them. For more options on upgrading packages with `easy_install` see [http://peak.telecommunity.com/DevCenter/EasyInstall#upgrading-a-package upgrading a package]:
{{{#!sh
easy_install --upgrade setuptools
}}}

== Developing with Eclipse and !PyDev

If you are planning to develop using Eclipse, you should also read the [TracDev/DevelopmentWithEclipseAndPyDev Development with Eclipse and PyDev] page, after installing and configuring Trac in the next section.

== Installing and configuring Trac
 
=== Download Trac

You should get the Trac source code from one of the TracRepositories. For example, for Subversion from the command-line prompt:
{{{#!sh
svn co http://svn.edgewall.org/repos/trac/trunk/ trac-trunk
svn co http://svn.edgewall.org/repos/genshi/trunk/ genshi-trunk
cd genshi-trunk
python setup.py develop 
cd ../trac-trunk
python setup.py develop
cd ..
}}}

=== Create your test Trac environment

From the command-line prompt:
{{{#!sh
trac-admin test initenv
}}}

'''Note:''' Press return for every option.

=== Grant full access to anonymous users

{{{#!sh
trac-admin test permission add anonymous TRAC_ADMIN
}}}

'''Note:''' Don't do this in production!

=== Install the [th:TracDeveloperPlugin] (optional)

{{{#!sh
svn co http://trac-hacks.org/svn/tracdeveloperplugin/trunk/ tracdeveloperplugin
cd tracdeveloperplugin
python setup.py bdist_egg
cp dist/*.egg ../test/plugins
cd ..
}}}

=== Start Trac in development mode

{{{#!sh
tracd -r --port 8000 test
}}}

'''Note''': The `-r` command puts Trac into refresh mode so your code changes will show up quickly. See also the [TracIni#trac-section auto_reload] trac.ini flag, which should be used for the changes in Genshi templates to be picked-up as well.

To run `tracd` or work in the virtual environment, you must switch to the virtual environment each time a new shell is opened:
{{{#!sh
cd test
source bin/activate
}}}

=== Debugging Plugins

To debug a plugin, install it into your test environment using the command:
{{{#!sh
$ python setup.py develop -md /path/to/projenv/plugins
}}}

If you are experiencing troubles in debugging Trac code, make sure that `PYTHONPATH` in project properties doesn't contain pointers to other Trac sources. Otherwise those sources will be picked instead of the checked out sources.

=== Open Trac in your browser

Switch to your browser and go to `http://127.0.0.1:8000/test` 

Now do the following:
 * Go to web admin
 * Click on Admin
 * Set logging:
  - Set type to `console`
  - Set level to `debug`

=== Alternative frontends

To develop on Trac with Apache rather than the standalone `tracd`, see the [TracDev/AlternativeFrontends alternative frontends] page for information on using Apache with mod_python and mod_wsgi.

== Further guidelines

Check the [/roadmap milestones] pages to see if there are any specific requirements for the version you are setting up. Specifically, for Trac 0.12+, you need Genshi 0.6 or later. See milestone:0.12 for more information.

The (automated) tests will require additional packages that may or may not be installed with your OS/Python distribution.  
 *  For unit test, please review [../UnitTests].
 *  For the functional test, please review [../FunctionalTests].