Creating a language project using CBS on SVN

Here is how to create a language project that provides an editor for a programming language together with a translator from programs to funcons. The language project is generated from CBS specifications of syntax and semantics. The CBS specifications of funcons can be shared between different language projects in the PLanCompS SVN repository using SVN externals.

This version refers to the new CBS-beta, Funcons-beta, and Languages-beta folders, in preparation for the beta-release.

N.B. It is now no longer necessary to include (links to) CBS specifications inside generated translators. This not only simplifies creation of translators, but also allows generated translator projects to be cleaned independently of the CBS specifications.

Platform requirements

The procedure described below has been tested on the following platforms:

The following procedure should work also on previous versions of Mac OSX, and on other Linux systems.

Creating a language project

As a running example, we explain how to create a translator for a language named LANG. Language names should be short, start with a capital letter, and may consist of letters, digits, and hyphens (but not underscores).

The following language names are reserved for internal use: CBS, Funcons, SDF (and its variations) and Stratego.

The following extensions are reserved for internal files: ast, cbs, config, fct, sdf (and its variations) and str.

The name of the folder containing the CBS specification of LANG and the LANG translator could be simply LANG. Below, we use LANG-Folder instead, to avoid confusion with the files and sub-folders named LANG.

  1. It is assumed that in the SVN repository:

  2. Ensure the following file and folder names are all ignored by SVN:

        .cache
    .classpath
    .project
    .settings
    bin
    src-gen
    target

  3. Link to Funcons-beta in the PLanCompS SVN repository:

    Hovering over the references to names (and any section numbers) in the CBS files should now show (right-clickable) hyperlinks to their declarations. If not, select the project and click on Project: Clean....

    If Build automatically is off, also select the project and click on on Project: Build.

  4. Create a Spoofax language project using Eclipse with the following settings:

    and the following language option settings:

    The generation options determine whether extra projects for storing examples and automated tests will be created.

    Open the Console view in Eclipse (Window: Show View: Other...).

    Click on Finish to create the project. It can take a few minutes. The progress is logged in the Spoofax Console.

Generating a language editor and translator

Note: Eclipse may initially flag various errors and warnings in the generated files. The errors should all disappear when the LANG-Editor project has been successfully built; some warnings (e.g., about overloaded constructors in SDF3 files) may remain, but can be ignored.

  1. Open LANG-cbs/LANG/LANG-Start/LANG-Start.cbs.

    Click on Spoofax: Generate: Language editor.

    The Spoofax console window should report something like the following:

    - Generating LANG components...
- Generating LANG-Start
- Generating LANG-Disambiguation
- Generating LANG-3
- Generating LANG-1
- Generating LANG-2
- Generating LANG-4
- Finished

    (The Spoofax build process sometimes starts before generation has completed. If that happens, clean the generated LANGEditor project before proceeding.)

    The LANGEditor/syntax folder should now contain the generated files Funcons.sdf3 and Stratego-LANG.sdf, and a folder cbs-gen containing SDF3 files generated from the CBS files for the language LANG.

    The LANGEditor/trans folder should now contain the generated files generate.str and generate.meta, and a folder cbs-gen containing Stratego and meta files generated from the CBS files for the language LANG. (No files are generated for funcons.)

    A new folder LANGEditor/lib should have been created, containing the generated file StrategoMix.def.

    The LANGEditor/editor folder should contain the generated file Menus.esv.

    Note: Never edit the generated files, as they are overwritten by Generate: language editor.

  2. Update the following files:

Building and testing the generated project

Assuming the CBS specification of LANG is complete, the translation of the LANG program to funcons should appear in (e.g.) test.fct.

Updating the generated project

After editing a CBS file in LANG-cbs, with LANGEditor open:

Executing funcon terms

The final state of an execution of the funcon term should be reported in the Console.

Generating a funcon reuse index

The file LANG-Funcon-Index/LANG-Funcon-Index.cbs should be generated, listing all the funcons (etc.) used in cbs/LANG files.

Generating web pages

For each file cbs/LANG/X/X.cbs, the web page cbs/LANG/X/index.html should be generated.

The HTML uses a relative link to load the CSS file Funcons-beta/cbs.css, and relative hyperlinks from funcon names to their declarations. This requires Funcons-beta to be located as a sibling of the parent of the folder that contains the LANG-Editor project, as in the SVN repository:

CBS-beta
- Funcons-beta
- Languages-beta
- - LANG-Folder
- - - LANG-Editor

(Browsing HTML files in LANG-Folder/LANG-cbs requires a copy of Funcons-beta – or a link to it – one level higher in the file system.)

The dynamic features of the web pages work as intended in Safari and Eclipse. They allow sections, comments, and rules to be collapsed (individually or collectively), and a fixed menu provides links to LANG-Start and Funcons-Index.