Program Structure, Project Types, Program Entry Point
A typical ELENA project consists of a project file (.prj) and source files (.l) located in the project root and sub folders.
Root source files are declared in the project root namespace, ones in sub folders - in nested namespaces.
E.g.
<project>
<namespace>mytest</namespace>
</project>
<files>
<module>
<include>test.l</include>
<include>subns\test.l</include>
</module>
</files>
test.l file is declared in mytest namespace, subns\test.l one in mytest'subns.
NOTE : By default all source files are UTF8 encoded. The project file is an XML document with configuration root node. In the current implementation the project file contains no xml namespace attributes
Typically the project compilation produces a single module file (.nl). But it is possible to specify multi-library output:
<project>
<namespace>mytest</namespace>
</project>
<files>
<module>
<include>test.l</include>
<include>subns\test.l</include>
</module>
<module name="sub1">
<include>sub1\op.l</include>
<include>sub1\sub2\op2.l</include>
</module>
</files>
In this case several libraries will be generated - mytest.nl and mytest\sub1.nl
A project file contains the project settings, source files, forwards and so on. The project may be based on a project template. In this case it inherits all the parent settings except the overloaded ones. The template may be based on another one and so on.
| XPath | Descriptions |
|---|---|
| configuration/project/debuginfo | -1 / 0 - turn on/off the debug information generation |
| configuration/project/executable | the project target name (a name of the generated executable file) |
| configuration/project/libpath | a path to the language libraries |
| configuration/project/namespace | a project root namespace |
| configuration/project/output | a path to the output directory |
| configuration/project/template | a project base template |
| XPath | Descriptions |
|---|---|
| configuration/linker/heapcommit | specifies total heap allocation size in physical memory, the default value is 65536 |
| configuration/linker/heapresrv | specifies total heap allocation size in virtual memory, the default value is 1048576 |
| configuration/linker/imagebase | specifies the image base address, the default value is 4194304 (40000h) |
| configuration/linker/mgsize | specifies the initial size of GC generation 1 in hexadecimals |
| configuration/linker/stackcommit | specifies the total stack allocation size in physical memory, the default value is 4096 |
| configuration/linker/stackresrv | specifies the total stack allocation size in virtual memory, the default value is 1048576 |
| configuration/linker/ygsize | specifies the size of GC generation 0 in hexadecimals |
| XPath | Descriptions |
|---|---|
| configuration/system/maxthread | specifies the maximal number of simultaneous threads |
| configuration/system/platform | specifies the target platform |
maxthread should 0 or 1 for the STA (single-thread application) and more than 1 for MTA (multi-thread application)
platform defines the target platform
| Target | Descriptions |
|---|---|
| 0 | a library |
| 1 | Win32 CUI (console user interface) stand-alone STA |
| 4097 | Win32 GUI (graphical user interface) stand-alone STA |
| 257 | Win32 CUI (console user interface) vm-client STA |
| 65537 | Win32 CUI (console user interface) stand-alone MTA |
| XPath | Descriptions |
|---|---|
| configuration/compiler/l0 | -1 / 0 - turn on/off the byte-code level optimization |
This section provides the module manifest info
| XPath | Descriptions |
|---|---|
| configuration/manifest/name | specifies the module name |
| configuration/manifest/version | specifies the module version |
| configuration/manifest/author | specifies the module author |
This section contains the list of source and the target libraries. It may specifies the parsing target for the script files.
In the simplest case it contains the list of source file names:
<configuration>
<files>
<module>
<include>controls.l</include>
<include>win32_controls.l</include>
<include>win32_forms.l</include>
</module>
</files>
<configuration>
The files will be compiled into the single module in the root namespace specified in configuration/project/namespace
If files contains sub-folder the appropriate nested namespace will be used:
<configuration>
<files>
<module>
<include>convertors.l</include>
<include>console.l</include>
<include>win32_args.l</include>
<include>basic.l</include>
<include>random.l</include>
<include>math\functions.l</include>
<include>text\strings.l</include>
<include>text\words.l</include>
</module>
</files>
</configuration>
e.g math\functions.l will be compiled in math sub-namespace
Several configuration\files\module can be used. Only one of them may omit the name attribute. As a result several modules will be generated:
<configuration>
<project>
<namespace>mytest</namespace>
</project>
<files>
<module>
<include>test.l</include>
<include>subns\test.l</include>
</module>
<module name="sub1">
<include>sub1\op.l</include>
<include>sub1\sub2\op2.l</include>
</module>
</files>
</configuration>
here several libraries will be produced - mytest.nl and mytest\sub1.nl in mytest and mytest'sub1 namespaces.
<configuration>
<files>
<module name="rules" target="eson">
<include>calc.es</include>
</module>
<module>
<include>parser.l</include>
<include>control.l</include>
</module>
</files>
</configuration>
configuration\files\module may have target attribute which will be used to compile user-defined grammar source files. Appropriate targets should be declared in the configuration\targets section.
configuration\forwards section contains the list of weak references which are resolved in a link time.
<forwards>
<forward key="$program">system'startUp</forward>
<forward key="$system_entry">system'core_routines'sta_start</forward>
<forward key="program">$elena'@rootnamespace'program</forward>
</forwards>
A key attribute contains the forward name, the node body - the resolved reference.
The system forward names start with a dollar sign ($), the program ones are normal identifiers and may contain a namespace prefix.
Forwards are used for example to resolve the program entry.
configuration\primitives section contains the list of binary files used by the linker
configuration\references section contains the list of paths to the external libraries (the ones which are not located in the folder specified in configuration/project/libpath)
configuration\targets section contains the list of script engine setting to parse the specified files with an external grammar.
Currently several major project templates are supported:
- console - STA CUI stand-alone application (templates\win32_console.cfg)
- mta_console - MTA CUI stand-alone application (templates\win32_consolex.cfg)
- gui - STA GUI stand-alone application (templates\win32_gui.cfg)
- mta_gui - MTA GUI stand-alone application (templates\win32_guix.cfg)
- vm_console - STA CUI vm-client application (templates\vm_win32_console.cfg)
- lib - ELENA library (templates\lib.cfg)
where :
- CUI - console user interface
- GUI - graphical user interface
- STA - single-thread application
- MTA - multi-thread application
The program entry is defined by the project forward references. The system entry is defined in $system_entry, the program one - in $program. The system entry is used to initialize the program environment (e.g. initialize a system environment record, allocate a program heap and so on). The system entry in its turn invoke the program entry point. In most cases the program entry invokes the program main symbol (for the CUI) or the program main window (for GUI).
The program main symbol / window should be declared in the project root namespace. For console application the symbol name should be - program, for graphical application - MainWindow
