[[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, we create a standalone Python environment.

=== Create a working directory

Create a working directory for your development to take place in. For example, on Unix you might have:
{{{
/home/<user>/projects
}}}

On Windows you might 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 installation directions there.

=== Get Python

On Linux, you'll usually want 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 python
}}}

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 has Python pre-installed, but you probably want to install a newer version using a package manager such as [https://brew.sh/ Homebrew].

=== Get pip

You'll already have `pip` installed with Python >= 2.7.9. If you are running an earlier version of Python, first check whether `pip` is already installed:
{{{#!sh
$ pip --version
}}}
Use [https://pip.pypa.io/en/stable/installing/#installing-with-get-pip-py get-pip.py] if you need to install `pip`.

=== Get virtualenv

You may already have `virtualenv` installed.
{{{#!sh
$ virtualenv --version
}}}

If you need to install `virtualenv`, or you wish to upgrade the package:
{{{#!sh
$ pip install -U virtualenv
}}}

You may need to prefix the command with `sudo` on Unix platforms.

=== Set up a virtual environment

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

or for Windows:
{{{#!cmd
# python -m virtualenv pve
# cmd /k Scripts\activate.bat
}}}

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

=== Upgrade Dependencies

Upgrade the dependencies in your environment.
{{{#!sh
$ pip install -U pip setuptools wheel
}}}

== 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, to checkout from Subversion using the command-line:
{{{#!sh
$ svn co https://svn.edgewall.org/repos/trac/trunk/ trac-trunk
}}}

Install the packages in development mode:
{{{#!sh
$ pip install -e trac-trunk
}}}

For Trac >= 1.3.2 you'll need Jinja2:
{{{#!sh
$ git clone https://github.com/pallets/jinja.git jinja2
$ pip install -e jinja2
}}}

=== Create a Trac environment

From the command-line prompt:
{{{#!sh
$ trac-admin tracenv initenv "TracDev" sqlite:db/trac.db
}}}

=== Grant full access to anonymous users

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

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

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

{{{#!sh
$ svn co https://trac-hacks.org/svn/tracdeveloperplugin/trunk/ tracdeveloperplugin
$ pip install tracdeveloperplugin/
}}}

=== Start Trac in development mode

{{{#!sh
$ tracd -r -s --port 8000 tracenv
}}}

'''Note''': The `-r` command puts Trac into refresh mode so your code changes will immediately take effect. See also the [TracIni#trac-auto_reload-option auto_reload] option in trac.ini, which causes template changes to take effect immediately.

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 /path/to/projects
$ source pve/bin/activate
}}}

=== Developing Plugins

To develop a plugin, checkout the source and install it in development mode using the command:
{{{#!sh
$ pip install -e /path/to/plugin/src
}}}

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

=== Open Trac in your browser

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

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 developing against. Specifically, for Trac 1.3.2+, you need Jinja2 2.9.3 or later. See milestone:1.3.2 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].