<?xml version="1.0" encoding="UTF-8"?>
<chapter version="5.1" xmlns="http://docbook.org/ns/docbook"
         xmlns:xlink="http://www.w3.org/1999/xlink"
         xmlns:xila="http://www.w3.org/2001/XInclude/local-attributes"
         xmlns:xi="http://www.w3.org/2001/XInclude"
         xmlns:trans="http://docbook.org/ns/transclusion"
         xmlns:svg="http://www.w3.org/2000/svg"
         xmlns:m="http://www.w3.org/1998/Math/MathML"
         xmlns:html="http://www.w3.org/1999/xhtml"
         xmlns:db="http://docbook.org/ns/docbook">
  <?xxe-sn 2ckdfwgr1fk 1?>

  <title><?xxe-sn 2ckdfwgr1fk 2?>Installation</title>

  <section>
    <?xxe-sn 2ckdfwgr1fk 6?>

    <title><?xxe-sn 2ckdfwgr1fk 7?>Build on Linux</title>

    <para><?xxe-sn 2ckdfwgr1fk 8?>Major dependencies:</para>

    <itemizedlist>
      <?xxe-sn 2ckdfwgr1fk 9?>

      <listitem>
        <?xxe-sn 2ckdfwgr1fk a?>

        <para><?xxe-sn 2ckdfwgr1fk b?>gcc 7</para>
      </listitem>

      <listitem>
        <?xxe-sn 2ckdfwgr1fk c?>

        <para><?xxe-sn 2ckdfwgr1fk d?>llvm 5, clang 5</para>
      </listitem>

      <listitem>
        <?xxe-sn 2ckdfwgr1fk e?>

        <para><?xxe-sn 2ckdfwgr1fk f?>boost 1.66</para>
      </listitem>

      <listitem>
        <?xxe-sn 2ckdfwgr1fk g?>

        <para><?xxe-sn 2ckdfwgr1fk h?>coco</para>
      </listitem>

      <listitem>
        <?xxe-sn 2ckdfwgr1fk i?>

        <para><?xxe-sn 2ckdfwgr1fk j?>clingo</para>
      </listitem>
    </itemizedlist>

    <para><?xxe-sn 2ckdfwgr1fk k?>Building tested on <emphasis
    role="bold"><?xxe-sn 2ckdfwgr1fk l?>OpenSuse Leap 15</emphasis>. Please
    change commands accordingly if using other distributions.</para>

    <para><?xxe-sn 2ckdfwgr1fk m?>Pull sources directly from
    repository:</para>

    <literallayout><?xxe-sn 2ckdfwgr1fk n?>git clone --recursive http://xreate.org/diffusion/XR/xreate.git</literallayout>

    <para><?xxe-sn 2ckdfwgr1fk o?>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:</para>

    <remark><?xxe-sn 2ckdfwgr1fk p?>"Enter into source directory" - тут перед
    directory явно нужен артикль. Гугл говорит, что определенный -
    the</remark>

    <important>
      <?xxe-sn 2ckdfwgr1fk q?>

      <para><?xxe-sn 2ckdfwgr1fk r?>Carefully inspect scripts before
      run</para>
    </important>

    <para><?xxe-sn 2ckdfwgr1fk s?>On <emphasis role="bold"><?xxe-sn 2ckdfwgr1fk t?>OpenSuse
    Leap 15</emphasis>:</para>

    <literallayout><?xxe-sn 2ckdfwgr1fk u?>./installation/prepare-opensuse-leap15</literallayout>

    <para><?xxe-sn 2ckdfwgr1fk v?>That was one time operation to prepare
    environment. After that enter into <code><?xxe-sn 2ckdfwgr1fk w?>build</code>
    directory and start actual tests building:</para>

    <remark><?xxe-sn 2ckdfwgr1fk x?>"build directory": здесь ты все-таки
    вначале указываешь имя объекта (build), и лишь потом родовое название
    (directory)</remark>

    <literallayout><?xxe-sn 2ckdfwgr1fk y?>cd build
make</literallayout>

    <para><?xxe-sn 2ckdfwgr1fk z?>After successful build you can run xreate
    tests:</para>

    <literallayout><?xxe-sn 2ckdfwgr1fk 10?>cd ..
./build/tests/xreate-tests</literallayout>

    <note>
      <?xxe-sn 2ckdfwgr1fk 11?>

      <para><?xxe-sn 2ckdfwgr1fk 12?>Please pay attention that the working
      directory should be the repository root</para>
    </note>

    <para><?xxe-sn 2ckdfwgr1fk 13?>For consequent rebuilds after updates etc
    invoke <code><?xxe-sn 2ckdfwgr1fk 14?>cmake</code> as follows:</para>

    <literallayout><?xxe-sn 2ckdfwgr1fk 15?>#working dir build
cmake -DCMAKE_BUILD_TYPE=Debug \
      -DBUILD_XREATE_TESTS=1   \
      -DCOCO_EXECUTABLE=&lt;FILE&gt; \
      -DCLINGO_PATH=&lt;DIR&gt;      \
      -DCOCO_FRAMES_PATH=../vendors/coco/generator/  \
      -DCMAKE_CXX_COMPILER=g++ ../cpp
make</literallayout>

    <para><?xxe-sn 2ckdfwgr1fk 16?><code><?xxe-sn 2coi7ojavb4 a?>cmake</code>'s
    selected parameters:</para>

    <itemizedlist>
      <?xxe-sn 2ckdfwgr1fk 17?>

      <listitem>
        <?xxe-sn 2ckdfwgr1fk 18?>

        <para><?xxe-sn 2ckdfwgr1fk 19?>BUILD_XREATE_TESTS Determines whether
        to build tests</para>
      </listitem>

      <listitem>
        <?xxe-sn 2ckdfwgr1fk 1a?>

        <para><?xxe-sn 2ckdfwgr1fk 1b?>COCO_EXECUTABLE Full filename of Coco
        executable</para>
      </listitem>

      <listitem>
        <?xxe-sn 2ckdfwgr1fk 1c?>

        <para><?xxe-sn 2ckdfwgr1fk 1d?>CLINGO_PATH Installed Clingo
        directory</para>

        <remark><?xxe-sn 2ckdfwgr1fk 1e?>"Directory of Clingo installation":
        может, with Clingo installation? (это если речь идет о папке, где
        хранятся инсталляционные файлы) Если наоборот, куда будет
        устанавливаться - тогда Directory for installing Clingo. Оригинальный
        вариант ("of Clingo installation") немного сбивает с толку.</remark>
      </listitem>
    </itemizedlist>
  </section>

  <section>
    <?xxe-sn 2coi7ojavb4 1?>

    <title condition="demo"><?xxe-sn 2coi7ojavb4 2?>Experimenting</title>

    <para><?xxe-sn 2coi7ojavb4 3?>At this point the only executable produced
    by <code><?xxe-sn 2coi7ojavb4 x?>make</code> is a collection of the unit
    tests. There are many existing unit tests located in the <code><?xxe-sn 2coi7ojavb4 y?>cpp/tests</code>
    to check correctness of various compilation aspects. Unit tests are
    configured via the file <code><?xxe-sn 2coi7ojavb4 5?>config/default.json</code>
    with the relevant settings located in the section <code><?xxe-sn 2coi7ojavb4 6?>tests</code>.
    The section looks like this:</para>

    <literallayout><?xxe-sn 2coi7ojavb4 b?>"tests": { 
      "template": "default",
      
      "templates": {
        "default": "*",

        "documentation": "Modules.Doc_*:Modules_API.Doc_*",
        "ast": "AST.*",
        ...
      }
}</literallayout>

    <para><?xxe-sn 2coi7ojavb4 c?>Key <code><?xxe-sn 2coi7ojavb4 d?>tests.template</code>
    determines which group of unit tests should be executed, while section
    <code><?xxe-sn 2coi7ojavb4 e?>test.templates</code> 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. </para>

    <para><?xxe-sn 2coi7ojavb4 f?>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:</para>

    <itemizedlist>
      <?xxe-sn 2coi7ojavb4 g?>

      <listitem>
        <?xxe-sn 2coi7ojavb4 h?>

        <para><?xxe-sn 2coi7ojavb4 i?>Add new file to the <code><?xxe-sn 2coi7ojavb4 j?>cpp/tests</code>.</para>
      </listitem>

      <listitem>
        <?xxe-sn 2coi7ojavb4 k?>

        <para><?xxe-sn 2coi7ojavb4 l?>Register test by adding its filename to
        the variable <code><?xxe-sn 2coi7ojavb4 10?>TEST_FILES</code> in the
        <code><?xxe-sn 2coi7ojavb4 m?>test/CMakeLists.txt</code>.</para>
      </listitem>

      <listitem>
        <?xxe-sn 2coi7ojavb4 n?>

        <para><?xxe-sn 2coi7ojavb4 o?>Change <code><?xxe-sn 2coi7ojavb4 p?>config/default.json</code>
        accordingly.</para>
      </listitem>
    </itemizedlist>

    <para><?xxe-sn 2coi7ojavb4 q?>Below is a bare bones example of a unit-test
    as a starting point to get an idea:</para>

    <literallayout><?xxe-sn 2coi7ojavb4 r?>name="tests/unit-test-example: Example.Example1", lines=15
#include "xreatemanager.h"    //main Xreate header
#include "transcendlayer.h"
#include &lt;gtest/gtest.h&gt;

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&lt;XreateManager&gt; man(XreateManager::prepare(move(example)));
  
  //Add transcend part:
  man-&gt;transcend-&gt;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-&gt;run();
  
  //Now execute function and check the result
  int resultActual = yourEntryFn(5, 7);
  int resultExpected = 5 + 7;
  
  ASSERT_EQ(resultExpected, resultActual);
}</literallayout>

    <para><?xxe-sn 2coi7ojavb4 u?>It outlines common unit test structure:
    defines a program and optional transcend rules(in this case to designate
    <code><?xxe-sn 2coi7ojavb4 w?>sum</code> as an entry function). Then the
    program is compiled, executed and the result is checked against expected
    value. </para>

    <para><?xxe-sn 2coi7ojavb4 11?>Have a look at other existing unit tests
    and see <link xlink:href="/api"><?xxe-sn 2coi7ojavb4 z?>Internal
    API</link> to know more. </para>
  </section>
</chapter>
