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)