OpenEngine Distributions

  1. Working with Distribution
    1. Installing
    2. Updating
  2. Creating Distributions
    1. File Format
    2. Publication
    3. Example File

OpenEngine Distributions

An OpenEngine distribution is a bundle of projects, extensions, data files and library packages. The entire bundle is described by a distribution file that ends with the extension .dist

Working with Distribution

To work with distributions you must use the dist.py program that is bundled with the main OpenEngine source. How to obtain the source is described in detail on the Download page. After you have acquired a copy of OpenEngine you can get a listing of the available commands by running: 

./dist.py help

Installing

Installing a distribution is done with the install command followed by the location of a distribution file. The file could be on the net or a local file.

For example: 

./dist.py install http://openengine.dk/data/dists/default.dist

will install our default distribution on your system. This is done in three steps.

  1. The program will first download the distribution file at place it in the root of your source directory.
  1. After that it will ask if you would like to update the distribution repositories. This involves either fetching new repositories or pulling new updates from existing ones. The program will prompt you for each individual update. You may answer a at the prompts to signal yes to all.
  1. Finally it will ask if you would like to download the distribution data. This data consists of content in the form of models and textures, and also of libraries needed to compile and run the program on your operating system. The system will automatically unpack zip and tar files in the correct places.

The install command has a useful shortcut for installing OpenEngine projects. For any project, located in the official /code/projects directory that contains a distribution file of the same name, the install command will accept proj:SomeProject as a substitute for http://openengine.dk/code/projects/SomeProject/SomeProject.dist So installing SomeProject becomes as simple as: 

./dist.py install proj:SomeProject

Updating

After you have installed a distribution updating it becomes fairly easy. To update from the distribution repositories simply run: 

./dist.py update

To fetch new data sources run: 

./dist.py data

As expected the system will automatically unpack zip and tar files. Please note that the system will not delete the archives. This is because the system does not download data files twice, so leaving the file lets the system know that the file has been retrieved. If you wish to force the system to download the files anew, you must manually delete the archives and the files that it contained. If you omit to delete the unpacked files, the next unpacking will fail.

Both of the above commands work because the system looks for distribution files in your source directory. The command is then run on all the distributions it finds.

Note that you may very well have several distributions installed in one working copy of OpenEngine.

Both of the commands take an optional list for distributions to work on if you wish to specify such things explicitly.

Creating Distributions

File Format

A distribution file consists of comments and lines that bind a path to a resource of some type You may view the structure of a line as: 

<type>  <path>  <resource>

where the components are separated by whitespace. This means that there may be no spaces in the path or resource identifiers.

Comments are started by a hash mark #, and blank lines are ignored.

type
The type component specifies what type of binding we should create. Valid types are
  • darcs specifies a darcs repository.
  • win32 specifies a data source for a Windows system.
  • darwin specifies a data source for a Mac OS X system.
  • linux specifies a data source for a GNU/Linux system.
  • any specifies a data resource for any system.
The Python sys.platform value is used to identify the host system and any value or prefix hereof can be used as a data specifier.
path
The path component specifies what local path the resource should be bound to. For a data file it is the directory that the resource should be placed within. For a repository it is the containing folder.

The path must start with a slash "/" and the empty slash refers to the OpenEngine root directory.

resource
The resource specifies the location of the resource. The syntax depends on the type of the binding. For a darcs binding it may be any valid darcs repository resource. For a data resource it can be any path supported by Python's standard urllib.

Publication

As distribution files can be installed over the net, you are encourage to place your distributions online somewhere. We recommend adding a distribution file in the root of your project and uploading the project to the /code/projects directory. Do however make sure that your distribution file has the same name as your project (case included) and ends with .dist. If not, the installation shortcut will not work.

Example File

# Example Distribution
# This is a purely illustrative example.
# The mentioned repositories and resources probably don't exist.

# Main OpenEngine repository
darcs / http://openengine.dk/code/openengine

# Branch with my own system changes
darcs / http://openengine.dk/code/branches/my-branch-main

# Required extensions
darcs /extensions/SDL             http://openengine.dk/code/extensions/SDL
darcs /extensions/OpenGLRenderer  http://openengine.dk/code/extensions/OpenGLRenderer

# Some working project
darcs /project/OERacer http://openengine.dk/code/projects/OERacer

# Branch with my own changes for OERacer
darcs /project/OERacer http://openengine.dk/code/branches/my-branch-oeracer

# Libraries for various system
win32  /libraries http://openengine.dk/data/libraries/sdl-win32.zip
darwin /libraries http://openengine.dk/data/libraries/sdl-osx.zip
linux  /libraries http://openengine.dk/data/libraries/sdl-linux.zip

# Content
any /projects/OERacer/data http://openengine.dk/data/models/FutureTank.zip