Moving to setuptools
DONE This proposal has been integrated for the 0.11 release.
This page describes the plan to move to the setuptools package for deploying Trac.
Adopting setuptools brings a number of benefits, mostly centered around making installation easier and the plugin system more robust.
- Trac will become better suited to be installed using EasyInstall, including automatic downloading and installation of dependencies such as Genshi.
- Programs such as
tracdwill be installed as wrapper scripts suitable to the installation platform. For example, on Windows the programs will be installed as executables (
.exe), making them easier to invoke from the command prompt.
- Plugins will be able to declare compatibility with a specific version of Trac. Thus you could have a plugin that says it requires e.g.
"Trac>=0.11.3."(see declaring dependencies).
- We will be able to provide a common package namespace (called
tracext) that third-party developers could use for their plugin code, meaning the Python package namespace won't get polluted by those plugins.
- The listing of Trac modules in at the bottom of db_default.py will be replaced by entry points declared in the
setup.pyfile, and thus registered using the same mechanism already in use by external plugins.
- Optionally, we could support the entry point for WSGI app factories exposed by Paste Deploy.
Some aspects of how Trac is currently packaged and run need to be changed so that it can be deployed with setuptools.
trac.siteconfig, which is currently generated at installation time, will be removed. Its purpose was to tell Trac where to find various installation-wide directories and files such as
- static resources (htdocs),
- default wiki pages,
- the configuration file
The templates, static resources, and the default set of wiki pages will become package data, meaning they will be installed alongside the application code, and no longer intended to be modified by the site admin. Instead they should be overridden using a site template and a site-specific CSS stylesheet.
The other cases are mostly interesting for deployments handling multiple projects, where every project should inherit some aspects from a shared location. This scenario will be handled by allowing trac.ini to inherit configuration values from an explicitly specified “parent” configuration. For example, the
trac.ini file of an environment might start like this:
[inherit] file = /etc/trac.ini
The inherited configuration file could then specify global directories for the templates, plugins, and default wiki pages, in addition to most other options already usable with the global
This approach is both more explicit and more flexible than the current model. For example, it allows multiple inheritance levels, as opposed to the fixed global→environment levels we currently provide.
As the location of the global configuration file will no longer be available implicitly,
trac-admin will need to be modified so that this information can be passed to it using command-line options and/or environment variables.
$ trac-admin --inherit-file=/etc/trac.ini /var/trac/myproj initenv
$ export TRAC_CONFIG=/etc/trac.ini $ trac-admin /var/trac/myproj initenv
I'd like to combine this with making
trac-admin make use of options instead of positional arguments for the
initenv command, so that even a simple invocation as above would just create the environment, instead of prompting for information that can easily be provided later.
When moving the templates and htdocs into package data, should we try and split them up for the different subsystems? I.e. should all the ticket system templates live under
trac/ticket/templates, or together with all other templates in
[inherit] mechanism is quite flexible (ability to specify the various locations for everything), but there should probably be a way to specify one location where to look for all the various parts (could be the parent directory containing all the various package data, and expecting an
htdocs subfolders, a
templates subfolder, etc.).
The sandbox/setuptools@4821 branch contains most of the changes described, but is based on a rather old version of trunk. Because this proposal requires moving many files around (causing pain when merging), I would prefer doing these changes in one big changeset directly on trunk instead of updating the branch.
You can view the diff to get a feeling for the changes required.