Build and Run

Getting started

Build on Linux

Major dependencies:

• gcc 7
• llvm 5, clang 5
• boost 1.66
• coco
• clingo

Building tested on OpenSuse Leap 15. Please change commands accordingly if using other distributions.

Pull sources directly from repository:

git clone --recursive http://xreate.org/diffusion/XR/xreate.git

Enter into the source directory and run the following script to prepare building environment. Script will install the required system packages as well as Coco and Clingo from sources:

On OpenSuse Leap 15:

./installation/prepare-opensuse-leap15

That was one time operation to prepare environment. After that enter into build directory and start actual tests building:

cd build
make

After successful build you can run xreate tests:

cd ..
./build/tests/xreate-tests

For consequent rebuilds after updates etc invoke cmake as follows:

#working dir build
cmake -DCMAKE_BUILD_TYPE=Debug \
      -DBUILD_XREATE_TESTS=1   \
      -DCOCO_EXECUTABLE=<FILE> \
      -DCLINGO_PATH=<DIR>      \
      -DCOCO_FRAMES_PATH=../vendors/coco/generator/  \
      -DCMAKE_CXX_COMPILER=g++ ../cpp
make

cmake's selected parameters:

• BUILD_XREATE_TESTS Determines whether to build tests
• COCO_EXECUTABLE Full filename of Coco executable
• CLINGO_PATH Installed Clingo directory

Experimenting

At this point the only executable produced by make is a collection of the unit tests. There are many existing unit tests located in the cpp/tests to check correctness of various compilation aspects. Unit tests are configured via the file config/default.json with the relevant settings located in the section tests. The section looks like this:

"tests": { 
      "template": "default",
      
      "templates": {
        "default": "*",

        "documentation": "Modules.Doc_*:Modules_API.Doc_*",
        "ast": "AST.*",
        ...
      }
}

Key tests.template determines which group of unit tests should be executed, while section test.templates describes all available groups. Note, that exact syntax of unit tests selection is described in the Google Tests library documentation. By modifying this configuration you can choose which tests you want to execute.

In order to experiment with the compiler you need to write your own unit-tests. There are several steps to complete to add and run new unit tests:

• Add new file to the cpp/tests.
• Register test by adding its filename to the variable TEST_FILES in the test/CMakeLists.txt.
• Change config/default.json accordingly.

Below is a bare bones example of a unit-test as a starting point to get an idea:

#include "xreatemanager.h"    //main Xreate header
#include "transcendlayer.h"
#include <gtest/gtest.h>

using namespace xreate;
using namespace std;

TEST(Example, Example1){
  //(Optional) Your custom transcend rules if any
  string rules = 
  R"SCRIPT(
    bind_func("sum", entry).
  )SCRIPT";
    
  //Your custom program
  string example = 
  R"CODE(
    //Custom code
    
    sum = function(a:: int, b:: int):: int
    { 
      a + b
    }
  )CODE";
    
  //Initialize compiler  
  unique_ptr<XreateManager> man(XreateManager::prepare(move(example)));
  
  //Add transcend part:
  man->transcend->addRawScript(move(rules));
  
  //Define signature of your entry function:
  typedef int (*ENTRYFN)(int, int);
    
  //Compile the example and get a pointer to the entry function:
  ENTRYFN yourEntryFn =  (ENTRYFN) man->run();
  
  //Now execute function and check the result
  int resultActual = yourEntryFn(5, 7);
  int resultExpected = 5 + 7;
  
  ASSERT_EQ(resultExpected, resultActual);
}

It outlines common unit test structure: defines a program and optional transcend rules(in this case to designate sum as an entry function). Then the program is compiled, executed and the result is checked against expected value.

Have a look at other existing unit tests and see Internal API to know more.