Setting up a development and debug environment
If you would just like to use the application to view and edit bird related artefacts, then you dont need to follow this step. However if you would like to amend or debug the efbt project code, or have a simpler navigation in order to understand the code, then this is best done using the pre configured Eclipse development environment. We make use of a feature called Oomph profiles to easily set up a preconfigured Eclipse IDE suitable for developement on the project.
This document describes the steps to setup this environment.
If you have any problems with the setup you can raise a query on the efbt forum
You may require admin privileges to install software on your machine.
We use the eclipse installer to setup a custom Eclipse IDE for development, with all the required features preloaded. The 2 setup files required are part of the publicly available efbt github repository. Firstly we download those 2 setup files locally, the easiest way to do this is to go first to https://raw.githubusercontent.com/eclipse/efbt/develop/dev_setup/org.eclipse.efbt.oomph/FreeBIRDToolsProduct.setup and right click on the page and choose "Save Page As" and choose a place to save the file. Then go to https://raw.githubusercontent.com/eclipse/efbt/develop/dev_setup/org.eclipse.efbt.oomph/FreeBIRDTools.setup and right click on the page and choose "Save Page As" and choose a place to save the file.
When saving these files be careful not to accidentally change the file extension from .setup to .setup.txt by choosing to save as a txt file. You can rename the files to remove the .txt extension them if this occurs when saving.
Download the latest Eclipse Installer from https://www.eclipse.org/downloads/packages/
As of April 2024 the latest release is 2024-03
If using Windows , then run the downloaded exe.
If using linux/unix then extract the downloaded tar file, and run/double-click the eclipse_inst file.
On the top right corner choose advanced mode and choose to keep the installer in a permanent location. A link should appear on your desktop if you are using windows. Click on . Click on + in the top right, and then choose "browse file system" to choose the FreeBIRDToolsProduct.setup file that you saved earlier.
Note that if you had an older version of the setup file, you would need to delete the reference to it here first, then add the more recent one.
You should then see freebirdtools Profile added. Choose product version "latest", pick the justJ JRE 17 and ensure bundle_pools tickbox is clicked as follows:
Click next. You may find that freebird tools project has been added automatically to github projects, if not add it by selecting github Projects, then clicking + , then finding FreeBIRDTools.setup that you saved earlier.
**Note **that if you had an older version of the profile file, you would need to delete the reference to it here first, then add the more recent one.
Select this project by pressing the checkbox as follows:
Click Next.
Choose a local installation directory, and click on "look at all variables". for the freebirdtools Github repository field click the dropdown and choose "HTTP readonly /anonymous" as follows:
or you may want to choose git@github.com:eclipse/efbt.git if you will be commiting changes to the repository.
Also choose your version 17 JDK
Click Next then Finish, Accept the licenses . You may be asked if you accept the unsigned content , you can accept this.
If you are doing this for the first time it will take some time to download all the related stuff.
When it is finished you can click finish in the Eclipse installer, you will see "Press Finish to close the dialogue" An Eclipse workspace should open automatically, and it should execute startup tasks, which should set up a local git repository in the git sub directory of the installation directory you chose, it should clone the code from the GitHub website, and import it into Eclipse as folders.
In the unlikely case that this fails these steps would need to be done manually.
Close the welcome screen to see the folders.
This step also installs all necessary and useful tools to do development. It also installs all plugins which are required to build the project.
You will see under the chosen installation directory is now an eclipse directory which includes the eclipse executable needed to run the IDE in future, a ws (workspace directory) for storing working settings and eclipse configuration, and also a git directory which stores the code.
To simplify the navigation of the code we split the code into "working sets". To see these working sets click on the 3 dots which allows us to choose some presentation options in the Eclipe IDE as shown here : 
And then choose "top level elements->Working sets"
Then click again on the 3 dots and choose "select working set" and choose all working sets except for "Java Main Sources" and "Java Test Sources".
The Model Explorer tab in your IDE setup should then look like this:
A description of the file layout and overall design of Eclipse Free BIRD Tools is provided in a seperate wiki https://github.com/eclipse/efbt/wiki/File-Structure-and-Project-Design
Java files representing the Models are generated from the Ecore models.
Also the java code for a text editor for the DSL is generated from the Ecore models and a grammar file called regDNA.xtext. This .xtext file defines the grammar and how the Ecore classes can be used to store the contents of text written in that grammar.
These Java files are created by running the Maven script that exists in the root directory of the code called efbt. Instructions on running the Maven Script can be found at Building-the-application.
The Maven script will also compile all the Java files.
NB...due to issue https://github.com/eclipse/efbt/issues/1147 the maven script is currently not generating the java files for RegDNA, and so we generate them manually from the .genmodel file (see https://github.com/eclipse/efbt/wiki/Updating-Ecore-files) ...we check in the created java files, the maven script continues to compile these..If you do not need to change the ecore files (whichis the normal case), then you don't need to generate Java files from RegtDNA ecore files , since the generated Java files are already checked in to the repository.
After the Java classes are generated, if you wish to make small changes then these could be compiled by running the Maven script again. Alternatively they can be compiled in the IDE automatically if you set up the compiler settings as follows:
Compilation from within the IDE is well tested with JustJ 17,
Compilation should be done to compliance level of Java 17 , this should be set automatically in the windows->preference->Java->Compiler settings as below (with --release option checked)
Choose the "build automatically" option from the project dropdown menu to turn on automatic compilation after changes.
From tool bar choose Run -> run configurations
Double click on Eclipse Application
Change the name to efbt.
Under 'program to ruin' choose run a product, and select to org.eclipse.platform.ide from the dropdown.
Chose JavaSE17 as exection environment
Then click apply.
To run this configuration go again to Run -> run configurations, choose the efbt run configuration and click run.
To debug this configuration go again to run -> debug configurations, choose the efbt run configuration and click debug.
when you run or debug then second eclipse workbench should appear.
In debug mode you can set breakpoints in the initial IDE workbench.
Close the welcome tab if it appears.
Create a new Java project in the new eclipse workbench.
Under the src directory add create file called temp.regdna
When prompted choose to convert this to an XText projects
Write some regDNA (CTRL+Space will give you auto-complete options), for example:
package temp_package
type String wraps String
class abc
{
id String def
}
Generated ecore and Xcore artefacts will appear under the src-gen folder.