--------
This is a tutorial centered around creating a `Wordpress <http://wordpress.org/>`_
-repository. For the sake of demonstration,
-we shall assume that this repository hasn't been created yet.
-The repository then doesn't exist, we should create it::
+repository. It assumes you have an upstream; if you do not,
+you can skip most of these steps: just ensure you have a Git repository
+which contains a :term:`pristine` and :term:`master` branch,
+as well as tags for all of the releases in the form ``appname-1.2.3``
+and ``appname-1.2.3-scripts``.
+
+For the sake of demonstration, we shall assume that this repository
+hasn't been created yet. The repository then doesn't exist, we should
+create it::
cd "$WIZARD/srv"
mkdir wordpress
class Application(app.Application):
pass
+Finally, we have to tell Wizard about this new module. If you are
+creating this new module for Scripts, the easiest way to tell Wizard
+about the application is to add it to the :mod:`wizard_scripts`
+`setuptools plugin <http://aroberge.blogspot.com/2008/12/plugins-part-6-setuptools-based.html>`_.
+Even if you don't know anything about setuptools, it's pretty easy
+to add your application: edit the file :file:`plugins/scripts/setup.py`
+and add your application to the ``wizard.app`` entry point by looking
+for the following chunk of code and adding a new line::
+
+ 'wizard.app': ['mediawiki = wizard.app.mediawiki:Application',
+ 'phpBB = wizard.app.phpBB:Application',
+ 'wordpress = wizard.app.wordpress:Application', # NEW LINE!
+ ],
+
+This tells Wizard that there is a new application named ``wordpress``,
+with a module named ``wizard.app.wordpress`` and a class named
+``Application`` in that module, which Wizard should use.
+
+You need to refresh plugin information by running the :file:`refresh.sh`
+script or by running :file:`python setup.py egg_info` in the
+:file:`plugins/scripts` directory.
+
+.. note::
+
+ If you do not want to place your application in the Scripts plugin,
+ you will need to create a :file:`setup.py` file from scratch in your
+ own plugin. A reasonable template file is::
+
+ import setuptools
+
+ setuptools.setup(
+ name = 'wizard-myapp',
+ version = '0.1.dev',
+ author = 'Me',
+ author_email = 'my-email@mit.edu',
+ description = ('My Awesome Application'),
+ license = 'My Awesome License',
+ url = 'http://www.example.com/',
+ packages = setuptools.find_packages(),
+ entry_points = {
+ 'wizard.app': ['wordpress = wizard.app.wordpress:Application',
+ ],
+ }
+ )
+
+ Don't forget to run :file:`python setup.py egg_info` and add your module
+ to your :envvar:`PYTHON_PATH` (otherwise, Wizard won't know that
+ your plugin exists!)
+
Now we are ready to put some code in our repository: the first thing we will
add is the :term:`pristine` branch, which contains verbatim the code from upstream.
patch -n0 < /mit/scripts/deploy/wordpress-2.0.2/wordpress.patch
-Then, run the following command to setup a :file:`.scripts` directory::
-
- wizard prepare-new
-
-This directory holds Wizard related files, and is also used by
-:command:`parallel-find.pl` to determine if a directory is an autoinstall.
-
-Finally, if you are running a PHP application, you'll need to setup
+If you are running a PHP application, you'll need to setup
a :file:`php.ini` and symlinks to it in all subdirectories.
As of November 2009, all PHP applications load the same :file:`php.ini` file;
so just grab one from another of the PHP projects. We'll rob our own
to the connection, you can perform implicit execution.
To test if your installation function works, it's probably convenient to
-create a test script in :file:`tests`; :file:`tests/test-install-wordpress.sh`
+create a test script in :file:`tests`; :file:`tests/wordpress-install-test.sh`
in the case of Wordpress. It will look something like::
#!/bin/bash -e
+ cd `dirname $0`
DEFAULT_HEAD=1
- TESTNAME="install_wordpress"
+ TESTNAME="wordpress_install"
source ./setup
wizard install "wordpress-$VERSION-scripts" "$TESTDIR" --non-interactive -- --title="My Blog"
+.. note::
+
+ As you develop more test-scripts, you may find that you are
+ frequently copy pasting install commands. In this case, it may be
+ useful to create a 'wordpress-install' helper shell fragment and
+ source it whenever you need a vanilla installation.
+
``DEFAULT_HEAD=1`` indicates that this script can perform a reasonable
operation without any version specified (since we haven't tagged any of our
commits yet, we can't use the specific version functionality; not that we'd want
-to, though). ``TESTNAME`` is simply the name of the file with the leading
-``test-`` stripped and dashes converted to underscores. Run the script with
+to, though). ``TESTNAME`` is simply the name of the file with the trailing
+``-test`` stripped and dashes converted to underscores. Run the script with
verbose debugging information by using::
- env WIZARD_DEBUG=1 ./test-install-wordpress.sh
+ env WIZARD_DEBUG=1 ./wordpress-install-test.sh
The test scripts will try to conserve databases by running ``wizard remove`` on the
old directory, but this requires :meth:`~wizard.app.remove` be implemented.
the installation on a Scripts server. You can do this manually or use
the test script you created::
- env WIZARD_NO_COMMIT=1 ./test-install-wordpress.sh
+ env WIZARD_NO_COMMIT=1 ./wordpress-install-test.sh
:envvar:`WIZARD_NO_COMMIT` (command line equivalent to ``--no-commit``)
prevents the installer from generating a Git commit after the install, and will
#. Create the new repository and new module,
#. Implement :meth:`~wizard.app.Application.download`,
+#. Register the application at the ``wizard_scripts`` plugin,
#. *For Conversions:* Find the oldest extant version with ``wizard summary version $APP``,
#. Run ``wizard prepare-pristine $VERSION``,
#. Commit with ``-m "$APPLICATION $VERSION"`` and tag ``$APP-$VERSION``,
#. *For PHP:* Copy in :file:`php.ini` file and run ``athrun scripts fix-php-ini``,
#. Commit with ``-m "$APPLICATION $VERSION"``, but *don't* tag,
#. Implement :data:`~wizard.app.Application.install_schema` and :meth:`~wizard.app.Application.install`,
-#. Create :file:`tests/test-install-$APP.sh`,
+#. Create :file:`tests/$APP-install-test.sh`,
#. On a scripts server, run ``wizard install $APP --no-commit`` and check changes with ``git status``,
#. Implement :attr:`~wizard.app.Application.extractors`,
:attr:`~wizard.app.Application.substitutions`, :attr:`~wizard.app.Application.parametrized_files`,