The empty module is a top-level directory in the SVN-repository which contains everything you need to start your own project based on PHP-Front. The special name that is used for this 'project' is empty-module. This name can/should be replaced with the name of your own project.

This page explains the contents of the directory and the purpose of several files. TheExampleProject explains how this directory can be used in order to set up a new project. Note that the following explanation is based on the structure of PHP-Front and PHP-Sat. There is also an explanation available for Stratego programs in general.

The directory has three top-level directories: branches, tags and trunk. We will only discuss the contents of the trunk here because that is where the magic happens. You can find a good explanation of how to use the other directories here.

The directory contains the following directories (red) and files (blue):

config

This directory will contain the configuration files after you run the bootstrap file, just here for convenience.

doc

Documentation directory. It is a good practice to document the tools / library that you made in your project in different sub-directories.

src

The actual sources of your project, there are three different kind of sources:

grammar

Grammar sources are *.sdf files that define a grammar for your project, for example the grammar of your configuration file.
The grammar is usually defined in a sub-directory languages/empty-module with one file at top-level, empty-module.sdf. A good example is the PHP-Sat structure.

grammar/Makefile.am

This file is the input file for the generation of the actual Makefile. It already defines a grammar that should be defined in the languages/empty-module -directory with a toplevel file called empty-module.sdf.

lib

Library sources are libraries that should be build for your project. Making a library is useful if you want to make a set of tools that share common functionality. Library sources should be defined as normal stratego-files (*.str) which are placed in the directory empty-module/ with a top-level-file called empty-module.str.

lib/Makefile.am

This file is the input for the generation of the actual Makefile. It already defines a library called libempty-module.la, which is defined in the directory empty-module/ with a toplevel-file called empty-module.str. Apart from the library is also generates the signature-file of the grammar defined in the src/grammar/ -directory. It also compiles this grammar to a C-file so that it can be imported into the library.
The configuration is also aware of any *.meta files in the empty-module -subdirectory.

tools

Tool sources are the actual tools defined in *.str files. These files are build as separate tools that are linked to the PHP-Front-library and the libary you defined yourself.

tools/Makefile.am

This file is the input for the generation of the actual Makefile. It already defines one tool called empty-module.str which is defined in this directory.

Makefile.am

This file is the input for the generation of the actual Makefile. It just instruct make to go into the subdirectories.

tests

Contains all the tests of your project, please use this! Tests help you by thinking about the code you write, checking what you have done and making sure that you did not break anything. We have added two files that can serve as input for the Makefile for testing the different parts of your project.

Makefile.am-grammar

This file is the input for the generation of the actual Makefile. It defines a sdf-testsuite called empty-module.testsuite which should contain the tests for your grammar.

Makefile.am-libtool

This file is the input for the generation of the actual Makefile. It defines a tool called empty-module-tests that should test (a part of) your library or a tool. This tool should be defined in a file called empty-module-tests.str in the same directory.

AUTHORS

The name explains it all I guess.

bootstrap

This script will bootstrap your project and will generate all the actual Makefile-files and a script called configure. This configure script is used to find all the required tools that are necessary for the project.

Changelog

Use this file to keep track of the changes of your project, or just one line with upgraded project.

configure.ac

This file is the input file for the configuration of the actual configure -script. It defines the name of the project, the email-address of the project and the input files it should use to generate the configure -script. It also lists all the Makefile-files it should generate.

empty-module.pc.in

One of the two files used to create the _configure_-script. Should have a name and a description for the project.

empty-module.spec.in

One of the two files used to create the _configure_-script. Should have a summary and a URL for the project.

Makefile.am

Top-level Makefile.am which will generate the top-level Makefile. It just tells make to go into the subdirectories.

NEWS

This file should contain all the latests news about your project.

README

The name of this file explains exactly what needs to be in this file. Think about what the people that will use your project need to know before they install/use your project.

-- EricBouwers - 01 Jan 2007