= Developer setup for Trac =
This tutorial assumes you have SVN installed.  If you don't have SVN installed please go to the [http://subversion.tigris.org/ Subversion] website and follow the directions of installation there.  Currently, Python's "setup tools" does not work correctly with SVN 1.6, so it is best while/when working with Trac to use a 1.5
version of SVN.  See [http://bugs.python.org/setuptools/issue64 setuptools issue with SVN 1.6] for more information and the current status of this issue. 

== 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 [http://trac.edgewall.org/roadmap roadmap/milestones] page(s) to see if there are any specific requirements for the version you are
setting up.  

Specifically, for version 0.12 (the current trunk), if you use the trunk version of Genshi, more than a few of the functional tests will fail.  To resolve this issue,
you should install the [http://genshi.edgewall.org/intertrac/source%3Abranches/experimental/advanced-i18n Genshi advanced i18n] version until this branch is integrated into the trunk.  See http://trac.edgewall.org/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 http://trac.edgewall.org/wiki/TracDev/UnitTests 
 *  For the functional test, please review http://trac.edgewall.org/wiki/TracDev/FunctionalTests

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

Note: if you planning to develop using Eclipse you should also check [wiki:TracDev/DevelopmentWithEclipseAndPyDev Development with Eclipse and PyDev].

=== 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 easy_install ===
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
}}}

=== Get virtual env ===
From the command-line prompt type:
{{{
easy_install virtualenv
}}}

=== Set up a virtual environment ===
From the command-line prompt type:
{{{
virtualenv trac
cd trac
source bin/activate
}}}

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.

== Installing and configuring Trac ==
 
=== Downloading trac ===
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 trackdeveloperplugin ===
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.

=== 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 frontend: mod_python ===

Virtualenv can also be used with Apache and mod_python, but as mod_python will be a system install it will not be aware of the virutalenv without some configuration. For development this is useful as one Apache can serve various development versions in a more permanent way. This method will use the system Python, but will add the libraries from the virtualenv.

'''Step 1:''' Make a new frontend script that for instance can be stored in the virtualenv 'bin' directory.

{{{
#!python
#myvirtualtrac.py

import os
import site
site.addsitedir('/path/to/my/virtualenv/lib/python2.4/site-packages')

from trac.web.modpython_frontend import handler
}}}

'''Step 2:''' Update Apache config to use this script - add or update options according to the default mod_python setup like for instance found in TracModPython.

{{{
# Extend the path so Apache will find your script on path
PythonPath "['/path/to/my/virtualenv/bin'] + sys.path"

# Make mod_python use new frontend instead of trac.web.modpython_frontend
PythonHandler myvirtualtrac
}}}

=== Alternative frontend: mod_wsgi ===

Using Apache, mod_wsgi is a very good alternative to mod_python. Setting this up follows the same pattern, but for development escpecially there is one major advantage: It can quite easily be set up to auto-reload on code changes.

'''Step 1:''' Update a default TracModWsgi setup to make a deamonised process, and as of mod_wsgi 2.0 (this setup depends on >= 2.0) there is built-in support for custom paths and similar. Example of a full `VirtualHost` configuration:

{{{
<VirtualHost *:80>
    ServerName virtualtrac.local

    # Update user and group to be whatever on your system is intended to run the deamon
    # Update the paths to point to virtualenv site-packages (for trac+++) and bin (for script)
    WSGIDaemonProcess virtualtrac user=www group=www threads=25 python-path=/path/to/my/virtualenv/lib/python2.4/site-packages:/path/to/my/virtualenv/bin

    WSGIScriptAlias / /path/to/my/virtualenv/bin/virtualtrac.wsgi

    <Location />
      WSGIReloadMechanism Process
      WSGIProcessGroup virtualtrac
      WSGIApplicationGroup %{SERVER}
      Order deny,allow
      Allow from all
    </Location>

    # Authentication
    <LocationMatch (/[^/.]+/login)>
      # Note: Change settings with regards to auth method, paths and domain
      AuthType Digest
      AuthName "virtualtrac"
      AuthDigestDomain /trac http://virtualtrac.local
      AuthDigestProvider file
      AuthUserFile /path/to/access.htdigest
      Require valid-user
    </LocationMatch>

</VirtualHost>
}}}

'''Step 2:''' Go to http://code.google.com/p/modwsgi/wiki/ReloadingSourceCode and save the long Python script that follows the text 'Example code for such an automatic restart mechanism...'. Save it as `/path/to/my/virtualenv/bin/monitor.py` 

'''Step 3:''' A basic WSGI frontend script, save as `/path/to/my/virtualenv/bin/virtualtrac.wsgi`

{{{
#!python

import sys
sys.stdout = sys.stderr

import os
os.environ['TRAC_ENV_DIR'] = "/path/to/trac/project"
# or, alternatively for multiple projects
#os.environ['TRAC_ENV_PARENT_DIR'] = "/parent/path/to/many/projects"
os.environ['PYTHON_EGG_CACHE'] = '/path/to/a/temp/to/cache/eggs'

import trac.web.main

import monitor
monitor.start(interval=1.0)
# Additionally monitor easy-install.pth to restart whenever installs are done
monitor.track('/path/to/my/virtualenv/lib/python2.4/site-packages/easy-install.pth')

application = trac.web.main.dispatch_request
}}}