Changes between Initial Version and Version 1 of TracDev/Proposals/Setuptools

Timestamp:

Jan 19, 2007, 1:57:17 AM (17 years ago)

Author:

Christopher Lenz

Comment:

Initial version

TracDev/Proposals/Setuptools

@@ +1 @@
+= Moving to setuptools =
+
+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.
+
+== Status ==
+
+The [source:sandbox/setuptools] 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: [milestone:0.11 Milestone 0.11], TracDev/Proposals