New Project Wizard format

The new project wizard has been rewritten for Anjuta 2. It is a generic plugin able to create different kind of projects. The files needed by each project and the associated graphical interface used to get user choices are defined in a text file read by the plugin. This documentation will described the format of this file which is called a template.


The template files look like xml documents and have normally the extension .wiz. All templates and others related files are installed by default in $anjuta_install_dir/share/anjuta/templates. But the project wizard looks for templates in the sub directory anjuta/templates of all user data directories as defined by XDG Base Directory Specification too. It is possible to override a Anjuta project template by an user one put, by example, in ~/.local/share/anjuta/templates.

The template file is divided in four parts: an header block, one or more page blocks, a content block and an optional action block. The file is read several times, one time for each block but before reading it, the whole file go though a transformation pass and only the resulting file must be a valid xml file. The transformation pass use autogen.

Autogen is a quite complete text transformation program, it is able to make string substitutions, conditionally generate text, include files and it can even be extended with the guile language. Autogen takes as input a template file which is the wizard template file and some definitions which are generated at run time according to the user choices. Note that the first line of an autogen template need to have special format not compatible with an xml file, so this line is added at run time when needed. It defines the start and end macros marker of autogen which is fixed and defined as "[+" and "+]" in the wizard template.

All blocks on the project wizard are included in a project-template block. This is needed because a valid XML file should have a single root block. This block was not used in older version of the format, so it is optional to keep backward compatibility.

The header block is the only exception, it is read directly from the template file and do not use autogen. It must be the first block and must be valid a xml block, that's why the first line of the template could not contains the autogen special line. The parsing is stopped when the end of this block is reached, so we do not care for the remaining of the file. This block contains informations about the project kind like a name and a short description.

The page blocks are read one by one after being transformed by autogen, they define some properties of the project which could be changed by the user, things like project name or use of a particular library. The graphical interface is created at run time according to these properties. Each page is generated when the user has completed all previous pages. You can ask the user for something on one page and his answers become available as autogen variables for generating the next page. You can, by example, skip a complete page for configuring a CVS reposit, if the user has decided to not use it. In case you insert or remove a complete page you need to take care to not do it before one already displayed.

When all pages have been displayed. The program will read the content block which defined all files and directories needed by the project. This block goes through autogen so you can use this to adjust file names and paths. Typically, at least creating a project file with the name given by the user. Note that the project files itself are transformed with autogen if needed.

Finally, if it exist the action block is read and the corresponding commands are executed in their order of apparition. Typically, it is useful for loading in Anjuta the newly created project.