Getting Started with the project
Welcome to the Elena Lang project!
Follow the steps below to get started with the project, from cloning the repository to running the tests.
Before you start, make sure you have the following applications installed:
Note: Building the project on previous versions of Visual Studio may not be possible.
Go to the Elena Lang GitHub repository.
Click on the "Fork" button at the top right of the page to create a copy of the repository under your GitHub account.
Open your visual studio.
Choose the "clone a repository" option.
Clone the repository:
the repo location is: https://github.com/your-username/elena-lang.git
Replace your-username with your GitHub username.
Click on the "Clone" button at the bottom right.
Click on "File" > "open" > "project/solution".
navigate to the project directory and choose the sln file (path/to/elena-lang/elenasrc3):
Click "open".
Click on "build" > "build solution" to execute the code.
Open PowerShell and navigate to the project directory:
"cd path/to/elena-lang"
Run the recompiler.bat file to build the project:
".\recompiler60.bat"
if everything is working you should get in the end:
--- Passed ---
=== Done ===
After you complete this process, run the test files to ensure everything is working correctly.
The test executables are located in the project directory at /bin and can be executed directly.
if everything runs - the set up is done!
The ELENA project is a complex system consisting of multiple components that work together to support the ELENA programming language. This is an overview of the project structure, the role of each component.
Purpose: Converts assembly code and byte-code to a format usable by the ELENA compiler.
Details:
Compiles assembly files located in ./asm//.asm.
Processes byte-code files used in the ELENA API (e.g., ./src60/core/*.esm).
Background: In the context of compilers, assembly code is a low-level representation of source code that is easier for a machine to execute. Byte-code is an intermediate representation, typically used by virtual machines to execute programs.
Purpose: Allows viewing and analyzing the contents of compiled modules and byte-code.
Details:
Views compiled module files (.nl files).
Displays generated methods and symbols' byte-code.
Background: Byte-code disassembly is useful for debugging and understanding how high-level code is transformed into a lower-level representation that the virtual machine can execute.
Purpose: The main compiler for the ELENA programming language.
Details:
Takes source code, parses it, and translates it into a format suitable for execution or further processing.
Background: This is a classic compiler that transforms high-level code into intermediate code (byte-code) and is central to the development workflow.
Purpose: Provides low-level routines for ELENA programs that are executed outside of the virtual machine.
Details:
Includes garbage collection, type routines, and message routines.
Background: A run-time library is crucial for managing memory, handling types, and providing essential services that support the execution of programs.
Purpose: Parses and executes runtime and compile-time scripts.
Details:
Handles GUI schemes and script execution (e.g., ./examples60/scripts/*).
Background: This engine allows for dynamic behavior and customization at runtime, often used for scripting and automating tasks within applications.
Purpose: Contains unit tests for the ELENA compiler.
Details:
Ensures that the compiler functions correctly through automated tests.
Purpose: Executes programs written in ELENA.
Details:
Includes similar low-level routines as elenart, but supports runtime class loading.
Background: Virtual machines provide a layer of abstraction between the compiled code and the hardware, allowing for features like dynamic class loading and platform independence.
Purpose: Integrated Development Environment for ELENA.
Details:
Provides tools and interfaces for developing ELENA applications.
Purpose: A terminal for interacting with the ELENA virtual machine.
Details:
Allows direct interaction and testing of ELENA programs within the virtual machine environment.
Purpose: Enables debugging of ELENA programs in VSCode.
Details:
Integrates with VSCode for debugging features, facilitating the development process.
Purpose: Generates documentation for the ELENA project.
Details:
Produces manuals and guides for users and developers.
Purpose: Generates optimization rules for the compiler.
Details:
Uses rules located in ./dat/og/*.
Helps the compiler recognize and apply optimization patterns.
Background: Optimization is critical for improving the performance of the compiled code. The rules help the compiler make decisions about how to transform and optimize the code.
Purpose: Generates grammar rules for the compiler.
Details:
Uses rules from ./dat/sg/*.
Produces syntax60.dat, which is used by the compiler’s parser.
Background: Grammar rules define the syntax of the programming language. The parser uses these rules to analyze and understand the source code.
-
{source code}: The starting point is the ELENA source code.
-
[elena_lang::Parser]: Parses the source code to generate a syntax tree. The syntax tree represents the hierarchical structure of the source code.
-
{syntax tree}: An intermediate representation of the source code's structure.
-
[elena_lang::Compiler]: Compiles the syntax tree into a build tree, which represents the code in a more detailed intermediate format.
-
{build tree>}: Contains class tables and methods, represented in byte-code.
-
[elena_lang::ByteCodeWriter]: Writes the build tree to a .nl module, which includes class tables and methods in byte-code format.
For Executables:
-
{class tables, class methods in byte codes}: The .nl module containing byte-code.
-
[elena_lang::JITLinker]: Converts the byte-code into native image sections, preparing it for linking.
-
{native image sections}: The intermediate representation for the native executable.
-
[elena_lang::Linker]: Links the native image sections to produce the final executable.
Role: Generates grammar rules used by elena_lang::Parser to understand and process the source code. The rules are critical for transforming the source code into an intermediate representation.
Role: Main compiler that uses the grammar rules from sg to parse source code, compile it into a build tree, and then into byte-code. The elena_lang::ByteCodeWriter component produces .nl files from the build tree.
Role: Compiles assembly code and byte-code used by the compiler. The byte-code produced by asmc can be incorporated into the .nl files generated by elena_lang::ByteCodeWriter.
Role: Provides optimization rules that the elena_lang::Compiler uses to optimize the byte-code during the compilation process.
Role: Disassembles and analyzes .nl files produced by ByteCodeWriter. This tool helps in debugging and understanding the structure of the compiled byte-code.
Role: Handles script parsing that may be utilized during compilation, especially for runtime or compile-time scripts, and for configuring GUI schemes.
Role: Provides an integrated development environment for coding in ELENA. It integrates with elc to facilitate code development and testing.
Role: Provides debugging capabilities for ELENA programs in VSCode, integrating with elc for compiling and elenavm for runtime debugging.
Role: Provides runtime support for stand-alone ELENA programs, including essential routines for execution.
Role: Executes programs written in ELENA, providing low-level routines and supporting dynamic class loading. The virtual machine interacts with the compiled .nl files and byte-code.
Role: Allows interaction with and testing of programs running on the ELENA virtual machine.
Role: Generates documentation related to the compiler and the entire ELENA project, including details about the integration and usage of various components.
This order follows the flow from source code preparation and compilation through optimization, debugging, and final execution, showing how each component integrates into the overall process.
