rodinaarssen/clair

C Language Analysis in Rascal

ClaiR - C Language Analysis in Rascal

ClaiR provides a mapping from the Eclipse CDT open C and C++ front-end to a Rascal M3 model for further processing. It can work with and without working from inside the Eclipse IDE.

Required software

You need Rascal, and Either Eclipse or VScode or the standalone Rascal jar:

• Eclipse 2019-06 or higher with our without the CDT tools (see here). With the CDT tools you have some more tools to access information from CPP projects (like include paths), but otherwise Clair functions the same.
  • In Eclipse install the Rascal plugin from the update site: https://update.rascal-mpl.org/stable/
• Or, VScode with the Rascal extension
  • Use the extension view in VScode to install Rascal
• Or, Rascal commandline (see here)

CAVEAT: currently both VScode and Eclipse Rascal releases have issues with Maven projects that depend on libraries such as clair. Please sit tight while we fix these.

How to use ClaiR once you have Rascal installed:

• Create an empty project "myproject" in a folder named "myproject"
• In META-INF/RASCAL.MF add Project-Name: myproject Source: src and `Require-Libraries: |lib://clair|
• In pom.xml add:

<dependency>
    <groupId>org.rascalmpl</groupId>
    <artifactId>clair</artifactId>
    <version>0.3.0</version>
</dependency>

• And (optionally) add in pom.xml this to be able to run mvn rascal:console and the Rascal compiler:

<plugins>
    <plugin>
        <groupId>org.rascalmpl</groupId>
        <artifactId>rascal-maven-plugin</artifactId>
        <version>0.7.3</version>
        <configuration>
            <bin>${project.build.outputDirectory}</bin>
            <srcs>
                <src>${project.basedir}/src</src>
            </srcs>
        </configuration>
        <executions>
            <execution>
                <id>rascal-compile</id>
                <phase>compile</phase>
                <goals>
                    <goal>compile</goal>
                </goals>
            </execution>
            <execution>
                <id>rascal-package</id>
                <phase>pre-package</phase>
                <goals>
                    <goal>package</goal>
                </goals>
            </execution>
        </executions>
    </plugin>
</plugins>

• note to skip running the Rascal compiler: mvn compile -Drascal.compile.skip

How to run

• On the commandline, in your own project, run mvn rascal:console, or
• In Eclipse's Project Explorer, right click a project's folder and select Rascal Console. The console should open inside Eclipse's terminal window with the title "Rascal [project: , mode: debug]". If, instead, it shows "project: none", make sure you clicked the project and the project is actually open.
• Or in VScode start a Rascal terminal from the command pallette, or from the "Start Rascal Terminal" action in an Rascal editor.
• Import ClaiR into the console by running import lang::cpp::AST;.
• To parse a string containing source code, call the parseString function, e.g., parseString("int foo() { return 0; }").
• To parse source files on disk, call the parseCpp function with a source location, e.g., parseCpp(|file:///tmp/example.cpp|), parseCpp(|project://clair/src/test/test.cpp|), parseCpp(|home://myFile.cpp|), or parseCpp(|file://C:/My%20Dir/main.cpp|).