{ "info": { "author": "Philipp von Weitershausen", "author_email": "philipp@weitershausen.de", "bugtrack_url": null, "classifiers": [ "Environment :: Console", "Framework :: Zope3", "Intended Audience :: Developers", "License :: OSI Approved :: Zope Public License", "Programming Language :: Python", "Topic :: Internet :: WWW/HTTP :: WSGI" ], "description": ".. contents::\n\nQuickstart\n==========\n\nYou can start a new Zope-based web application from scratch with just\ntwo commands::\n\n $ easy_install zopeproject\n $ zopeproject HelloWorld\n\nThe second command will ask you for a name and password for an\ninitial administrator user. It will also ask you where to put the\nPython packages (\"eggs\") that it downloads. This way multiple\nprojects created with ``zopeproject`` can share the same packages and\nwon't have to download them each time (see also `Sharing eggs among\nsandboxes`_ below).\n\n(Note: Depending on how they installed Python, Unix/Linux users may\nhave to invoke ``easy_install`` with ``sudo``. If that's not wanted\nor possible, ``easy_install`` can be invoked with normal privileges\ninside a `virtual-python`_ or workingenv_).\n\nAfter asking these questions, ``zopeproject`` will download the\n`zc.buildout`_ package that will be used to build the sandbox, unless\nit is already installed locally. Then it will invoke ``buildout`` to\ndownload Zope and its dependencies. If you're doing this for the first\ntime or not sharing packages between different projects, this may take\na while.\n\nWhen ``zopeproject`` is done, you will find a typical Python package\ndevelopment environment in the ``HelloWorld`` directory: the package\nitself (``helloworld``) and a ``setup.py`` script. There's also a\n``bin`` directory that contains scripts, such as ``paster`` which can\nbe used to start the application::\n\n $ cd HelloWorld\n $ bin/paster serve deploy.ini\n\nYou may also use the ``helloworld-ctl`` script which works much like\nthe ``zopectl`` script from Zope instances::\n\n $ bin/helloworld-ctl foreground\n\nAfter starting the application, you should now be able to go to\nhttp://localhost:8080 and see the default start screen of Zope. You\nwill also be able to log in with the administrator user account that\nyou specified earlier.\n\nNotes for Windows users\n-----------------------\n\nSome packages required by Zope contain C extension modules. There may\nnot always be binary Windows distributions available for these\npackages. In this case, setuptools will try to compile them from\nsource which will likely fail if you don't have a compiler such as the\nMicrosoft Visual C compiler installed. Alternatively, you can install \nthe free MinGW_ compiler:\n\n1. Download ``MinGW-x.y.z.exe`` from http://www.mingw.org/ and run it \n to do a full install into the standard location (ie. ``C:\\MinGW``).\n\n2. Tell Python to use the MinGW compiler by creating\n ``C:\\Documents and Settings\\YOUR USER\\pydistutils.cfg``\n with the following contents::\n\n [build]\n compiler=mingw32\n\n3. Let Python know about the MinGW installation and the\n ``pydistutils.cfg`` file. To do that, go to the *Control Panel*,\n *System* section, *Advanced* tab and click on the *Environment\n variables* button. Add the ``C:\\MinGW\\bin`` directory to your\n ``Path`` environment variable (individual paths are delimited by\n semicolons). Also add another environment variable called ``HOME``\n with the following value::\n\n C:\\Documents and Settings\\YOUR USER\n\nWhen installing packages from source, Python should now automatically \nuse the MinGW compiler to build binaries.\n\nSharing eggs among sandboxes\n----------------------------\n\nA great feature of `zc.buildout`_ is the ability to share downloaded\nPython packages (\"eggs\") between sandboxes. This is achieved by\nplacing all eggs in a shared location. zopeproject will ask for this\nlocation each time. The setting will become part of ``buildout.cfg``.\n\nIt could very well be that your shared eggs directory is different\nfrom the suggested default value, so it would be good to avoid having\nto type it in every time. Furthermore, you may want to avoid having\nsystem-dependent paths appear in ``buildout.cfg`` because they hinder\nthe repeatibility of the setup on other machines.\n\nA way to solve these problems is to configure a user-specific default\neggs directory for buildout in your home directory:\n``~/.buildout/default.cfg``::\n\n [buildout]\n eggs-directory = /home/philipp/eggs\n\nzopeproject will understand that you have this default value and\nchange its own default when asking you for the eggs directory. If you\njust hit enter there (thereby accepting the default in\n``~/.buildout/default.cfg``), the generated ``buildout.cfg`` will not\ncontain a reference to a path.\n\nCommand line options for zopeproject\n====================================\n\n``--no-buildout``\n When invoked with this option, ``zopeproject`` will only create the\n project directory with the standard files in it, but it won't\n download and invoke ``zc.buildout``.\n\n``--newer``\n This option enables the ``newest = true`` setting in\n ``buildout.cfg``. That way, buildout will always check for newer\n versions of eggs online. If, for example, you have outdated\n versions of your dependencies in your shared eggs directory, this\n switch will force the download of newer versions. Note that you can\n always edit ``buildout.cfg`` to change this behaviour in an existing\n project area, or you can invoke ``bin/buildout`` with the ``-n``\n option.\n\n``--svn-repository=REPOS``\n This option will import the project directory and the files in it\n into the given subversion repository and provide you with a checkout\n of the ``trunk``. ``REPOS`` is supposed to be a repository path\n that is going to be created, along with ``tags``, ``branches`` and\n ``trunk`` below that. This checkin ignores any files and directories\n created by zc.buildout.\n\n``-v``, ``--verbose``\n When this option is enabled, ``zopeproject`` won't hide the output\n of ``easy_install`` (used to install ``zc.buildout``) and the\n ``buildout`` command.\n\nThe sandbox\n===========\n\nWhat are the different files and directories for?\n-------------------------------------------------\n\n``deploy.ini``\n Configuration file for PasteDeploy_. It defines which server\n software to launch and which WSGI application to invoke upon each\n request (which is defined in ``src/helloworld/startup.py``). You\n may also define WSGI middlewares here. Invoke ``bin/paster serve``\n with this file as an argument.\n\n``debug.ini``\n Alternate configuration for PasteDeploy_ that configures \n middleware which intercepts exceptions for interactive debugging.\n See `Debugging exceptions`_ below.\n\n``zope.conf``\n This file will be read by the application factory in\n ``src/helloworld/startup.py``. Here you can define which ZCML file\n the application factory should load upon startup, the ZODB database\n instance, an event log as well as whether developer mode is switched\n on or not.\n\n``site.zcml``\n This file is referred to by ``zope.conf`` and will be loaded by the\n application factory. It is the root ZCML file and includes\n everything else that needs to be loaded. 'Everything else' typically\n is just the application package itself, ``helloworld``, which then\n goes on to include its dependencies. Apart from this, ``site.zcml``\n also defines the anonymous principal and the initial admin principal.\n\n``setup.py``\n This file defines the egg of your application. That definition\n includes listing the package's dependencies (mostly Zope eggs) and\n the entry point for the PasteDeploy_ application factory.\n\n``buildout.cfg``\n This file tells `zc.buildout`_ what to do when the buildout is\n executed. This mostly involves executing ``setup.py`` to enable the\n ``HelloWorld`` egg (which also includes downloading its\n dependencies), as well as installing PasteDeploy_ for the server.\n This files also refers to the shared eggs directory\n (``eggs-directory``) and determines whether buildout should check\n whether newer eggs are available online or not (``newest``).\n\n``bin/``\n This directory contains all executable scripts, e.g for starting the\n application (``paster``), installing or reinstalling dependencies\n (``buildout``), or invoking the debug prompt (``helloworld-debug``).\n It also contains a script (``python``) that invokes the standard\n interpreter prompt with all packages on the module search path.\n\n``src/``\n This directory contains the Python package(s) of your application.\n Normally there's just one package (``helloworld``), but you may add\n more to this directory if you like. The ``src`` directory will be\n placed on the interpreter's search path by `zc.buildout`_.\n\n``var/``\n The ZODB filestorage will place its files (``Data.fs``, lock files,\n etc.) here.\n\nRenaming\n--------\n\nYou can rename or move the sandbox directory any time you like. Just\nbe sure to run ``bin/buildout`` again after doing so. Renaming the\nsandbox directory won't change the name of the egg, however. To do\nthat, you'll have to change the ``name`` parameter in ``setup.py``.\n\nSharing and archiving sandboxes\n-------------------------------\n\nYou can easily share sandboxes with co-developers or archive them in a\nversion control system such as subversion. You can theoretically\nshare or archive the whole sandbox directory, though it's recommended\n**not to include** the following files and directories because they\ncan and will be generated by zc.buildout from the configuration files:\n\n* ``bin/``\n\n* ``parts/``\n\n* ``develop-eggs/``\n\n* all files in ``var/``\n\n* all files in ``log/``\n\n* ``.installed.cfg``\n\nIf you receive a sandbox thas has been archived (e.g. by checking it\nout from a version control system), you will first have to bootstrap\nit in order to obtain the ``bin/buildout`` executable. To do that,\nuse the ``buildout`` script from any other sandbox on your machine::\n\n $ .../path/to/some/sandbox/bin/buildout bootstrap\n\nNow the sandbox has its own ``bin/buildout`` script and can be\ninstalled::\n\n $ bin/buildout\n\nDeveloping\n==========\n\nFirst steps with your application\n---------------------------------\n\nAfter having started up Zope for the first time, you'll likely want to\nstart developing your web application. Code for your application goes\ninto the ``helloworld`` package that was created by zopeproject in the\n``src`` directory.\n\nFor example, to get a simple \"Hello world!\" message displayed, create\n``src/helloworld/browser.py`` with the following contents::\n\n from zope.publisher.browser import BrowserPage\n\n class HelloPage(BrowserPage):\n def __call__(self):\n return \"