tombuuz / ru.hse.nml

nML Lighter

nML Lighter is a plugin for IntelliJ IDEA that provides a code editor for the nML architecture decription language.

The plugin is developed by Dagvanorov Lkhagvajav as his course work at Faculty of Computer Science of Higher School of Economics. The supervisor is Andrei Tatarnikov.

The code editor is designed as a supplement for the MicroTESK verification framework and is based on the same dialect of nML.

nML-related presentations

• Video of the "Machine-Readable Specifications of RISC-V ISA" presentation by Alexander Kamkin done at RISC-V Summit in 2018.

nML-related publications

• M. Freericks. The nML Machine Description Formalism.
• M. Freericks et al. Describing Instruction Set Processors Using nML.
• A. Kamkin, A. Tatarnikov et al. Specification-Based Test Program Generation for ARM VMSAv8-64 Memory Management Units.
• A. Kamkin, A. Tatarnikov et al. MicroTESK: Specification-Based Tool for Constructing Test Program Generators.
• A. Kamkin, A. Tatarnikov et al. Maintaining ISA Specifications in MicroTESK Test Program Generator.
• A. Kamkin, A. Tatarnikov et al. Test Program Generator MicroTESK for RISC-V.
• A. Kamkin, P. Putro et al. Deductive Binary Code Verification Against Source-Code-Level Specifications.

ru.hse.nml's Issues

Support for preprocessor and revisions

Need to implement support for preprocessor directives and revisions.

List of language constructs to be supported:

Preprocessor:

 #include
 #define
 #undef
 #ifdef
 #ifndef
 #else
 #endif

Revisions:

 @rev(REV_ID)

Revision file format:

https://github.com/andrewt0301/ispras-microtesk-riscv/blob/master/microtesk-riscv/src/main/arch/riscv/revisions.xml

See example here:

https://github.com/andrewt0301/ispras-microtesk-riscv/tree/master/microtesk-riscv/src/main/arch/riscv/model

Travis CI is needed for the project

Need to compile the project using Travis CI.
This is done in most of projects at GitHub.

Implement a commenter

Implement a commenter for nML.

This one of the simples features, but it is very useful. Guide:

https://www.jetbrains.org/intellij/sdk/docs/tutorials/custom_language_support/commenter.html

The nML comment style is the same as in Java:

1. single line - //
2. multiline start - /*
3. multiline end - */

Support for the mmuSL language

We are also planning to support an nML extension called mmuSL (language for modelling memory management unit). If we have time.

For now, please create classes MmuLanguage and MmuFileType.
Also, use the same commenter as for nML (see issue #6) - need to add a corresponding record into XML.

Please add .gitignore file.

Please add .gitignore file. This is need to avoid adding irrelevant file types into the project.

Irrelevant files are: IntelliJ IDEA project and intermediate files produced by the build.

For example: https://github.com/andrewt0301/Java-Problems/blob/master/.gitignore

Need a proper icon for nML files

The current icon is bad.

1. Too large (see the picture below). The size must be 16 px. See IntelliJ icon guidelines: https://jetbrains.design/intellij/principles/icons/

2. Not related to the domain. nML describes microprocessor architecture. So, it must be a microprocessor. Try to find something in the Internet. It must be a free icon. We do not want to violate copyrights. Or, if you can, draw something yourself.

Have you already tested your plugin? I suspect, no. Here is how to do this:

Use Intellij/Google code style

Please follow code style recommended by Intellij.

https://www.jetbrains.org/intellij/sdk/docs/basics/intellij_coding_guidelines.html

There guidelines are rather abstract. More specific recommendations are give by Google (they use a similar code style):

https://github.com/google/styleguide

For enforce this code style, please install Google code style configuration into you Intellij IDEA:

https://github.com/google/styleguide/blob/gh-pages/intellij-java-google-style.xml

Select "Intellij IDEA | Preferences | Editor | Code style | Java". See the image below.

Correct language name is "nML" in any textual descriptions.

The correct name of the language is nML.

File extension ".nml" is OK, class name "Nml*" is also OK.

However, in all other textual descriptions and string literals that refer to the language name, it must be "nML".

File type name in XML must match the value in Java

Component names in Java classes and XML configuration file must match.

    @NotNull
    @Override
    public String getName() {
        return "Nml file";
    }

Wrong:

 -        <fileType name="Nml language" implementationClass="ru.hse.nml.NmlFileType"

Correct:

+        <fileType name="Nml file" implementationClass="ru.hse.nml.NmlFileType"

Move ANTLR files.

ANTLR files (*.g4) need to be moved to a special folder (conventions require so):

ru.hse.nml/src/main/antlr/ru/hse/nml/

Checkstyle must be used to enforce Google code style

Checkstyle must be used to enforce Google code style. The Gradle script must be updated to support this.

Checkstyle tool:
https://checkstyle.org/index.html

Gradle plugin:
https://docs.gradle.org/current/userguide/checkstyle_plugin.html

Configuration for Google style:
https://github.com/checkstyle/checkstyle/blob/master/src/main/resources/google_checks.xml

Add copyright information to the project.

Subject.

I suggest Apache License 2.0. JetBrains uses it for their open-source projects.
An example is in my repository:
https://github.com/andrewt0301/Java-Problems

Modern version of Gradle

Need a newer version of Gradle (most recent build of version 5) that can correctly work for IntelliJ IDEA 19.3.

gradle/wrapper/gradle-wrapper.properties:

distributionUrl=https\://services.gradle.org/distributions/gradle-5.6-bin.zip