[[PageOutline(2-5,Contents,pullout)]]
= Developer setup for Trac =

== Where to go for more information ==
It is also a good idea to review a couple of documents before attempting to install a development environment or even to install from the trunk.  One such place
(currently) is to review the [/roadmap milestones] page(s) to see if there are any specific requirements for the version you are setting up.  

Specifically, for version 0.12 and later, you need to use 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]

== Installing the development tools ==
Before we begin to develop in Trac, or even download Trac code, first create a standalone environment.

=== Create a working directory ===
No matter my operating system, I like to create a projects or working directory for my development efforts.  So for example on some systems, I might have:
{{{
/Users/myname/projects
}}}
On Windows I would have:
{{{
c:\projects
}}}

'''Note:''' I don't create a directory called 'trac' yet. That comes later!  In the meantime, cd (change directory) to your projects directory.

=== Get Subversion ===
This tutorial assumes you have SVN installed.  If you don't have SVN installed please go to the [http://subversion.apache.org/ Subversion] website and follow the directions of installation there.

=== Get Python ===

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

You will also need some additional libraries:
{{{
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].
 * ActiveState [http://www.activestate.com/activepython/ ActivePython]

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

=== Get easy_install ===
You may already 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], save it as ez_setup.py on your hard drive, then from the command-line prompt type:
{{{
python ez_setup.py
}}}

To test if the installation was successful, try typing from command-line prompt:
{{{
easy_install --help
}}}

=== Get virtualenv ===
From the command-line prompt type:
{{{
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:
{{{
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, make sure to run the above virtualenv command with --no-site-packages.

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

=== Upgrade Setuptools ===
Just to be sure you have a recent enough version of setuptools you may try to upgrade them (this was necessary on Ubuntu 10.04 Beta). For more options on upgrading packages with easy_install see [http://peak.telecommunity.com/DevCenter/EasyInstall#upgrading-a-package upgrading a package].
{{{
easy_install --upgrade setuptools
}}}

== Developing with Eclipse and !PyDev ==
If you 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 ==
 
=== Downloading Trac ===

You should get the Trac source code from one of the TracRepositories.

For example, for Subversion (from the command-line prompt):
{{{
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 ..
}}}



=== Creating your test Trac environment ===
From the command-line prompt:
{{{
trac-admin test initenv
}}}
'''note:''' Press return for every option.

=== Make anonymous users have full access ===
{{{
trac-admin test permission add anonymous TRAC_ADMIN
}}}
'''note:''' Don't do this in production!

=== Installing the tracdeveloperplugin ===
From the command-line prompt:
{{{
svn co http://trac-hacks.org/svn/tracdeveloperplugin/trunk/ tracdeveloperplugin
cd tracdeveloperplugin
python setup.py bdist_egg
cp dist/*.egg ../test/plugins
cd ..
}}}

=== Starting trac in development mode ===

From the command-line prompt:
{{{
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.
{{{
cd test
source bin/activate
}}}

=== Debugging Plugins ===
To debug a plugin, install it to your test environment using the command:
 {{{
 $ 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.

=== Web stuff ===
Switch to your browser and go to this URL:

http://127.0.0.1:8000/test 

Now lets follow a few more steps

 * Go to web admin
 * Hit the admin link
 * Logging
  - Set type to console
  - level to debug

=== Alternative frontends ===
To develop on Trac with Apache, Cherokee, or other web servers rather than the standalone tracd, see the [TracDev/AlternativeFrontends alternative frontends] page for information on using Apache with mod_python and mod_wsgi.