Freon Documentation (version 0.5.0)

Installing and Using Freon

Be sure to have node.js and yarn running. We are typically using the latest versions of all, although older versions likely work just as well. You could also try and use npm instead of yarn.

There are two ways to start with Freon, either use our Example project or use our Template project.

Start with the Example Project

The simplest manner to start working with Freon is to clone the example project from GitHub. In the following the root of your project will be indicated with ’~‘.

Clone branch master from https://github.com/freon4dsl/Freon-example.git in your preferred IDE. (For an explanation of the content of the project see Project_Structure).
Next, install all necessary packages by running:
```
yarn install
```
Run the generator and see the generated files appearing in the folder ~/src/picode:
```
yarn generate
```
Start the server (note that anything that is saved in the editor will be stored in ~/modelstore):
```
yarn model-server
```

Open another (bash) terminal, and start the generated editor from it:

yarn prepare-app   # Needed to generate the runtime CSS files.
yarn dev

Open browser at localhost

The last command opens your preferred browser with the generated editor for the language `Entity` on `http://localhost:5000/`. If Chrome is not your preferred browser, please open the above page in Chrome, because we cannot ensure that the editor functions as it should in other browsers."

Try out the editor

Use Help Menu

If you are having trouble using the editor, have a look at the key-bindings under the Help menu.

Start with the Template project

Another way to start working with Freon is to clone our template project from GitHub. The template project provides a shell for the generated editor that enables the user to work with multiple models and model units. In the following the root of the project will be indicated with ’~‘.

Clone branch master from https://github.com/freon4dsl/Freon-template. (For an explanation of the content of the project see Project_Structure).
Next, install all necessary packages by running:
```
yarn install
```
Create a folder for your language in ~/src, to hold the definition files for your language. We usually call it defs, but any name will do. (Here the name defs will be used.)
Create a language definition file which defines the structure of your language. The extension of this file must be .ast. You can, for instance, copy EntityLanguage.ast from the Freon example to your own defs-folder. Or, you can follow the tutorial on language structure definition.

Only the language structure is required

To start, you only need to define the language structure, defaults will be generated for the editor, scoper, typer, and validator. This is called the first level of customization.

Next, adjust the scripts entry in the package.json file. The generate script should include your defs folder as well as the folder where you want the generated code to be stored. In the following screenshot, we use ~/src/defs and ~/src/picode, respectively.

Image 'packagejsonadjustment.png' seems to be missing — Figure 1. Screenshot of package.json

Run the generator and see the generated files appearing in the folder where you decided to store the generated code (in the screenshot we used src/picode):

    yarn generate

Adjust the configuration of the web application by changing the two lines in the file ~/src/webapp/config/WebappConfiguration.ts.

Figure 2. Screenshot of WebappConfiguration
Start the server (note that anything that is saved in the editor will be stored in ~/modelstore):
```
yarn model-server
```

Open another (bash) terminal, and start the generated editor from it:

yarn prepare-app   # Needed to generate the runtime CSS files.
yarn dev

Open browser at localhost

The last command opens your preferred browser with the generated editor for the language `Entity` on `http://localhost:3000/`. If Chrome is not your preferred browser, please open the above page in Chrome, because we cannot ensure that the editor functions as it should in other browsers.

Try out the editor

Use Help Menu

If you are having trouble using the editor, have a look at the key-bindings under the Help menu.

Next steps

Now you are ready for a closer look at Freon. You can for instance:

Have a look at how the example language is defined by browsing through the language definition files in the Freon Example project. You can find them in ~/src/defs.
Read Developing a language to see how you can create your own language.
Have a look at the structure of the generated project.
See what the different options there are for calling the Freon generator.

If you are working with Webstorm, you might consider installing the plugin Awesome Console. This plugin redirects a click on an error message in the console to the correct position in any of the language definition files.