From 5b3e74b8c302d04a922a519306e9dd24681a2db6 Mon Sep 17 00:00:00 2001 From: Eduardo Santos Date: Tue, 9 Dec 2025 23:22:35 +0100 Subject: [PATCH] Revised version for the README file for clarity and updated instructions Updated the README to clarify the purpose and structure of exampleLang, and provided more detailed instructions on using the MAL Toolbox for compilation and testing. --- README.md | 138 +++++------------------------------------------------- 1 file changed, 11 insertions(+), 127 deletions(-) diff --git a/README.md b/README.md index 9a557dd..8fd654d 100644 --- a/README.md +++ b/README.md @@ -1,139 +1,23 @@ # exampleLang -exampleLang is a MAL language intended to demonstrate the Maven -project structure of a MAL language. +`exampleLang` is a basic MAL language intended to demonstrate the standard project structure and essential components of a MAL language. It is designed to be used as a **minimal working example or a template** for developing new attack languages. -This project has the following structure: +This project structure is optimized for modern MAL development workflows, which typically involve working with the **MAL Toolbox** for compilation and integration. -* The file `pom.xml` is the Maven configuration file of the project. -* The directory `src/main/mal` contains the MAL specification - `exampleLang.mal`, which is the MAL specification of exampleLang. -* The directory `src/main/resources/icons` contains SVG icons for the - assets in exampleLang. -* The directory `src/test/java/org/mal_lang/examplelang/test` - contains the unit tests of exampleLang. +--- -## Apache Maven +## 🛠️ Tooling and Compilation -[Apache Maven](https://maven.apache.org/) is a build tool and -dependency management tool for Java projects. You can read more about -Maven at . Follow the -instructions at to download -Maven, and follow the instructions at - to install Maven. +All necessary tools for compiling, analyzing, and working with MAL languages are centralized in the MAL ecosystem. -## Building exampleLang and running the unit tests +### MAL Toolbox -The -[MAL compiler](https://github.com/meta-attack-language/malcompiler) -compiles MAL specifications (`.mal` files) into different formats, -using different backends. The reference backend generates Java code -that is suitable for testing purposes and evaluating your language. +For all development, compilation, and integration with analysis environments (such as Python), please refer to the main repository: -### Building with the reference backend and running the unit tests +* **MAL Toolbox Repository:** [https://github.com/mal-lang/mal-toolbox](https://github.com/mal-lang/mal-toolbox) -To compile exampleLang with the reference backend of the MAL compiler -and then run the unit tests, execute the following command from the -`exampleLang` directory: +### Compiling Your Language -``` -mvn test -``` +A detailed, step-by-step tutorial on how to compile a MAL language specification is available here: -This will invoke the MAL compiler's reference backend to generate -`.java` files under `target/generated-test-sources`. These `.java` -files and the unit tests in `src/test/java` will then be compiled -into `.class` files under `target/test-classes`. The unit tests will -then finally be executed. - -To only compile exampleLang into `.java` files, execute the following -command: - -``` -mvn generate-test-sources -``` - -To compile exampleLang into `.java` files and then compile these -`.java` files and the unit tests in `src/test/java` into `.class` -files, execute the following command: - -``` -mvn test-compile -``` - -To run a specific test class, execute the following command: - -``` -mvn test -Dtest=TestExampleLang -``` - -Where `TestExampleLang` is the test class. - -To run a specific test method in a test class, execute the following -command: - -``` -mvn test -Dtest=TestExampleLang#testNoPassword -``` - -Where `TestExampleLang` is the test class and `testNoPassword` is the -test method. - -## Using exampleLang as a template MAL language - -To create a new language using exampleLang as a template, you need to -do the following: - -* Create a new MAL language project using exampleLang as the template - * `cp -r exampleLang/ myLang/` -* Enter the directory of the new MAL language project - * `cd myLang/` -* Update `LICENSE` with a license of your choice - * Update copyright notices to reflect your license in - * `NOTICE` - * `README.md` - * `pom.xml` - * `src/main/mal/exampleLang.mal` - * `src/test/java/org/mal_lang/examplelang/test/*.java` -* Update `README.md` with relevant information about your language. - Information about how to use Markdown can be found at - . -* Update `pom.xml` to reflect your project - * Update `` with a reverse domain name that you can use - * Example: `com.example` - * Update `` with a suitable name - * Example: `mylang` - * Update `` with the version of your language - * Example: `1.0.0` - * Update `` with the name of your language - * Example: `myLang` - * Update `` with the name of the main MAL specification - of your language - * Example: `myLang.mal` - * Update `` with the test package name of - your language - * Example: `com.example.mylang.test` -* Rename `src/main/mal/exampleLang.mal` to the name of the main MAL - specification of your language - * `mv src/main/mal/exampleLang.mal src/main/mal/myLang.mal` -* Update your main MAL specification's `#id` and `#version` - * Example: `#id: "com.example.mylang"`, `#version: "1.0.0"` -* Rename unit tests in `src/test/java` to reflect your language -* Change the package name of the unit tests to the test package name - of your language - * Example: `package com.example.mylang.test;` - -## License - -Copyright © 2020-2022 [Foreseeti AB](https://foreseeti.com) - -All files distributed in the exampleLang project are licensed under the [Apache License, Version 2.0](https://www.apache.org/licenses/LICENSE-2.0), except for the following files: - -| File | License | -| --- | --- | -| [`Host.svg`](src/main/resources/icons/Host.svg) | Host.svg "[Computer](https://thenounproject.com/term/computer/576625/)" icon by [✦ Shmidt Sergey ✦](https://thenounproject.com/monstercritic/) from [the Noun Project](https://thenounproject.com/) is licensed under [CC BY 3.0](https://creativecommons.org/licenses/by/3.0/). | -| [`Network.svg`](src/main/resources/icons/Network.svg) | Network.svg "[Network](https://thenounproject.com/term/network/691907/)" icon by [✦ Shmidt Sergey ✦](https://thenounproject.com/monstercritic/) from [the Noun Project](https://thenounproject.com/) is licensed under [CC BY 3.0](https://creativecommons.org/licenses/by/3.0/). | -| [`Password.svg`](src/main/resources/icons/Password.svg) | Password.svg "[Lock](https://thenounproject.com/term/lock/576530/)" icon by [✦ Shmidt Sergey ✦](https://thenounproject.com/monstercritic/) from [the Noun Project](https://thenounproject.com/) is licensed under [CC BY 3.0](https://creativecommons.org/licenses/by/3.0/). | -| [`User.svg`](src/main/resources/icons/User.svg) | User.svg "[User](https://thenounproject.com/term/user/581261/)" icon by [✦ Shmidt Sergey ✦](https://thenounproject.com/monstercritic/) from [the Noun Project](https://thenounproject.com/) is licensed under [CC BY 3.0](https://creativecommons.org/licenses/by/3.0/). | - -See [`LICENSE`](LICENSE) and [`NOTICE`](NOTICE) for details. +* **Compilation Tutorial:** [https://github.com/mal-lang/mal-toolbox-tutorial?tab=readme-ov-file#compiling-a-language](https://github.com/mal-lang/mal-toolbox-tutorial?tab=readme-ov-file#compiling-a-language)