Skip to content

Revised version for the README file for clarity and updated instructions #19

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
Esantos93 wants to merge 1 commit into
base: master
Choose a base branch
from
Open

Revised version for the README file for clarity and updated instructions #19

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
138 changes: 11 additions & 127 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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 <https://en.wikipedia.org/wiki/Apache_Maven>. Follow the
instructions at <https://maven.apache.org/download.cgi> to download
Maven, and follow the instructions at
<https://maven.apache.org/install.html> 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
<https://help.github.com/en/articles/basic-writing-and-formatting-syntax>.
* Update `pom.xml` to reflect your project
* Update `<groupId>` with a reverse domain name that you can use
* Example: `com.example`
* Update `<artifactId>` with a suitable name
* Example: `mylang`
* Update `<version>` with the version of your language
* Example: `1.0.0`
* Update `<name>` with the name of your language
* Example: `myLang`
* Update `<mal.file>` with the name of the main MAL specification
of your language
* Example: `myLang.mal`
* Update `<mal.reference.package>` 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) | <img src="src/main/resources/icons/Host.svg" alt="Host.svg" width="32" height="32"/> "[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) | <img src="src/main/resources/icons/Network.svg" alt="Network.svg" width="32" height="32"/> "[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) | <img src="src/main/resources/icons/Password.svg" alt="Password.svg" width="32" height="32"/> "[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) | <img src="src/main/resources/icons/User.svg" alt="User.svg" width="32" height="32"/> "[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)
Loading