[[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) into 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 into 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`
  - 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.