[[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//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 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 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 will 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 `virtualenv` is a tool to create isolated Python environments and allows you to test out Trac code or Python code in general without risk of data loss to the rest of your computer. 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 will see your command-line prompt prefixed with `(pve)` or similar. That means you have entered the virtual environment and your environment is ready for Trac installation and development. === 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 the Eclipse IDE, 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 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 a production environment! === 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/`. You should see the Trac landing page. 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].