Reference

This text is written both as a reference for distribution with PyMek, and as a chapter in the Cand. Scient. thesis that described the creation of PyMek. Some areas of the text may reflect this.

PyMek comes equipped with ten tasks as default. It is relatively easy to add new tasks, as long as you know enough Python to write it.

At the time of writing, some of these tasks could use more work in order to be genuinely platform-independent, but on most typical platforms, they will perform their duty well.

Creating new tasks

Creating a new task is simply a matter of creating a module for it to live in, and writing a class that subclasses the Task class in PyMek.tasks. Actually, due to Pythons ingenious "duck-typing", there is no need to subclass, as long as your task behaves like a Task object.

Task defines a constructor and a single method. The constructor takes four parameters, while the run method takes none.

As can be expected, run is called in order to execute the task. It relies on the constructor to provide it with details about what it is supposed to do.

The parameters given to __init__ (the constructor) are as follows:

Parameter	Meaning
target	The filename to create.
param	A list of parameters given in the PyMekfile.
deps	A list of filenames, the dependencies of this target.
sources	A list of filenames, the files created by the previous task.

The dependencies and sources deserve a closer explanation. Each task is required to return a list of files created. If the target has multiple tasks, the list of files created by the previous task is passed in to the next task in the sources parameter. If sources is not given, the default constructor will use deps instead.

Each parameter passed in at creation is stored in a variable with the same name, with the addition of an underline at the start. So the target parameter is available in the self._target variable.

Once you have written your class, you place it in a module and drop it into one of the locations PyMek searches for tasks. If you are not able to use the default directory, PyMek accepts options for new locations to search.

If you created a module mytasks, and the task mytask in that module, you would refer to it in a PyMekfile by the name mytasks.mytask. For the time being, PyMek does not support task packages, so a single module will have to do.

The default tasks

Here we will give a short introduction to each task, and the parameters it accepts. Parameters can be given on the commandline, in the configuration file, or in the PyMekfile.

Move and Copy

The tasks move and copy implement platform-independent move and copy operations, using Pythons shutil module. They take no options, and assume only one sourcefile.

reStructuredText

rst_compile will take one source, and run a suitable tool from the Python Docutils to create the target given.

In the configfile, or on the commandline, you can define a handler for a specific filetype. The options end with handler, and start with the filetype of a target. The value of that option will be used as the command to run in order to create a target of that type. If no handlers are defined matching the filetype, the two default handlers rst2html.py and rst2latex.py, for html and latex respectively, will be used.

If parameters are present in the PyMekfile, these are prepended with -- and added as options to the command that is being run.

LaTeX

latex will compile a LaTeX file to a DVI file. Any parameters given in the PyMekfile are added to the commandline, without processing. If the option latex is present in the configuration, this defines a new name for the latex-executable.

dvips and dvipdf

These two tasks are modeled after the LaTeX task, and behave identically, with different executables and optionnames as you would expect.

Java

The Java task will compile a Java source to bytecode. It takes one parameter, compiler, which can come from any of the three configuration sources. compiler defines which compiler to use. If none given, it will use the first found of javac, jikes and gcj with the -C option.

C/C++ compile

C_compile will compile C or C++ sources using the distutils CCompiler class. It accepts one option, include_dirs, a colon-separated list of directories with includefiles for the compiler.

C/C++ link

C_link will link C or C++ objects using the distutils CCompiler class. It accepts three options: type, library_dirs and libraries.

type defines which kind of target is being linked. The valid values are LIB, OBJ and EXE for shared library, shared object and executable, respectively.

library_dirs is a colon-separated list of directories the linker should use for finding libraries.

libraries is a colon-separated list of libraries to use during linking, in a platform-indepentent form. This usually means that there should be no fileextention, such as .so or .dll.

Generic Command

For all those cases where you can not accomplish the things you want with the available tasks, and you have no time or inclination to create one, you can probably get it to work with the GenCommand.

The parameters are joined together with spaces, and executed. A parameter that matches the text $target$ will be replaced with the value of self._target, while a parameter that matches $sources$ will be replaced with the sources, separated by spaces again.

Configuration options

In addition to the options accepted on the commandline, PyMek will accept the same options in a configurationfile. One option is only available in the configurationfile, and that is taskpaths. It contains a colon-separated list of directories to search for task-modules. These directories will be searched after the default location, so there is no way to override a default task with your own, apart from changing the PyMekfile.