= Moving to setuptools = ''DONE This proposal has been integrated for the [milestone:0.11] release. This page describes the plan to move to the [http://peak.telecommunity.com/DevCenter/setuptools setuptools] package for deploying Trac. == Benefits == 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 [http://peak.telecommunity.com/DevCenter/EasyInstall EasyInstall], including automatic downloading and installation of dependencies such as Genshi. * Programs such as `trac-admin` and `tracd` will 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. * [TracPlugins 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 [http://peak.telecommunity.com/DevCenter/setuptools#declaring-dependencies 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 [source:/branches/0.10-stable/trac/db_default.py db_default.py] will be replaced by entry points declared in the `setup.py` file, 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 [http://pythonpaste.org/deploy/ Paste Deploy]. == Required Changes == Some aspects of how Trac is currently packaged and run need to be changed so that it can be deployed with setuptools. === siteconfig === The module `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 * templates, * static resources (htdocs), * default wiki pages, * plugins, * the configuration file The templates, static resources, and the default set of wiki pages will become [http://peak.telecommunity.com/DevCenter/setuptools#including-data-files 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 [TracIni 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 `trac.ini` file. 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. === Environment Initialization === 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. For example: {{{ $ trac-admin --inherit-file=/etc/trac.ini /var/trac/myproj initenv }}} or: {{{ $ 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. == Open Questions == 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 `trac/templates`? ''Personally, I'd prefer splitting them up.'' -- ChristopherLenz [[br]] ''me too'' -- ChristianBoos [[br]] The `[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.). '' see #3897 and [http://dev.lazaridis.com/base/wiki/PlanEnvInheritance PlanEnvInheritance] '' -- ilias@lazaridis.com == Status == The [source: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:trunk@4131//sandbox/setuptools@4134 diff] to get a feeling for the changes required. ---- See also: [http://groups-beta.google.com/group/trac-dev/browse_thread/thread/e145c9e47bedcd0a Thread on trac-dev], [milestone:0.11 Milestone 0.11], TracDev/Proposals