Creating a new cube from scratch

--------------------------------

Let's start by creating the cube environment in which we will develop ::

  cd ~/cubes

  # use cubicweb-ctl to generate a template for the cube

  # will ask some questions, most with nice default

  cubicweb-ctl newcube mycube

  # makes the cube source code managed by mercurial

  cd mycube

  hg init

  hg add .

  hg ci

If all went well, you should see the cube you just created in the list

returned by ``cubicweb-ctl list`` in the  *Available cubes* section.

If not, please refer to :ref:`ConfigurationEnv`.

To reuse an existing cube, add it to the list named

``__depends_cubes__`` which is defined in :file:`__pkginfo__.py`.

This variable is used for the instance packaging (dependencies handled

by system utility tools such as APT) and to find used cubes when the

database for the instance is created (import_erschema('MyCube') will

not properly work otherwise).

On a Unix system, the available cubes are usually stored in the

directory :file:`/usr/share/cubicweb/cubes`. If you are using the

cubicweb mercurial repository (:ref:`SourceInstallation`), the cubes

are searched in the directory

:file:`/path/to/cubicweb_toplevel/cubes`. In this configuration

cubicweb itself ought to be located at

:file:`/path/to/cubicweb_toplevel/cubicweb`.

.. note::

    Please note that if you do not wish to use default directory for your cubes

    library, you should set the :envvar:`CW_CUBES_PATH` environment variable to

    add extra directories where cubes will be search, and you'll then have to use

    the option `--directory` to specify where you would like to place the source

    code of your cube:

    ``cubicweb-ctl newcube --directory=/path/to/cubes/library mycube``

.. XXX resurrect once live-server is back

.. Usage of :command:`cubicweb-ctl liveserver`

.. -------------------------------------------

.. To quickly test a new cube, you can also use the `liveserver` command for cubicweb-ctl

.. which allows to create an instance in memory (using an SQLite database by

.. default) and make it accessible through a web server ::

..   cubicweb-ctl live-server mycube

.. or by using an existing database (SQLite or Postgres)::

..   cubicweb-ctl live-server -s myfile_sources mycube