<?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 2b06cb2u4g0 1?>

  <title><?xxe-sn 2b06cb2u4g0 2?>Xreate Manual</title>

  <para><?xxe-sn 2b06cb2u4g0 6?>Xreate is an open source general purpose high
  level programming language designed to write efficient and safe computer
  programs.</para>

  <para><?xxe-sn 2b06cb2u4g0 8?>Here "high level" has very specific meaning,
  implying an ability to easily write, read, as well as adapt software to a
  constantly changing environment or business goals. In this respect, any
  software product can be evaluated on the basis of the three dimensions:
  efficiency, safety, and adaptability. Unfortunately, those properties are
  proved to be largely contradictory, for it is manageable to write either
  efficient (yet unsafe) or safe (yet impractical) code, but not both. Thus,
  the ultimate goal of the language is to allow developers to produce code
  that would have all these properties at the same time. Xreate's design
  principles allow to adopt any programming technique as long as it does not
  improve one dimension at the expense of another.</para>

  <para><?xxe-sn 2b06cb2u4g0 7?>To achieve the aforementioned design goals,
  Xreate employs three distinctive layers:</para>

  <itemizedlist>
    <?xxe-sn 2b06cb2u4g0 e?>

    <listitem>
      <?xxe-sn 2b06cb2u4g0 f?>

      <para><?xxe-sn 2b06cb2u4g0 g?><link xlink:href="/w/syntax"><?xxe-sn 2b06cb2u4g0 o?>Brute</link>.
      The lowest layer is called <emphasis><?xxe-sn 2b06cb2u4g0 p?>Brute
      </emphasis>— this is code that is intended to be actually compiled. Code
      on this level implements actual software functionality. It resembles the
      usual imperative languages' apparatus and consists of executable
      instructions such as arithmetic, branching, input/output, etc.</para>
    </listitem>

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

      <para><?xxe-sn 2b06cb2u4g0 j?><link xlink:href="/w/transcend"><?xxe-sn 2b06cb2u4g0 q?>Transcend</link>.
      Brute level alone is not enough to constitute a full-fledged language
      since code requires various non-executable metadata to express
      developer's intents, check correctness, validity and perform other types
      of analyses. In Xreate everything of this sort belongs to a layer called
      <emphasis><?xxe-sn 2b06cb2u4g0 s?>Transcend</emphasis>. Transcend due to
      its declarative nature is appropriate to do management-type work — it
      analyzes, oversees and controls brute by guiding compilation process.
      Everything on this level — logic or transcend facts and rules — is
      gathered and sent to an external logic solver to make solutions that are
      brought back in order to guide compilation.</para>
    </listitem>

    <listitem>
      <?xxe-sn 2b06cb2u4g0 l?>

      <para><?xxe-sn 2b06cb2u4g0 m?><link
      xlink:href="/w/concepts/interpretation/"><?xxe-sn 2b06cb2u4g0 r?>Interpretation</link>.
      There is also <emphasis><?xxe-sn 2b06cb2u4g0 t?>Interpretation</emphasis>
      — the intermediate level resembling dynamically typed languages that is
      used as a contact point and interpreter between brute and transcend and
      their respective low level and high level constructs and
      structures.</para>
    </listitem>
  </itemizedlist>

  <para><?xxe-sn 2b06cb2u4g0 u?>On a syntactic level, Xreate is a procedural
  language with extensive use of <emphasis><?xxe-sn 2b06cb2u4g0 v?><link
  xlink:href="/w/transcend"><?xxe-sn 2b06cb2u4g0 w?>annotations</link></emphasis>
  — arbitrary unconstrained metadata that software developer can attach to
  different language constructs, variables and code blocks. Annotations are
  completely invisible for the compiler proper and used by transcend more as a
  suggestion conveying additional information.</para>

  <remark><?xxe-sn 2ccp2iy80zj 1td6aqezxvj7l?>"a different language
  constructs": если подразумевается "конструкции разных языков", тогда лучше
  "different languages' constructs". Если конструкции языка, в целом, то тогда
  артикль a не нужен</remark>

  <para xlink:href="w/virtualization/"><?xxe-sn 2b3f3osfk74 g?>Most severe and
  hard to resolve problems in software development stem from interaction of
  different components on different levels. Each individual component often is
  thoroughly tested and works reliably. But combining them when building
  end-user software for which purpose complex interaction and extensive IO is
  enabled usually leads to a range of runtime errors, security vulnerabilities
  and performance degradation.</para>

  <para xlink:href="w/virtualization/"><?xxe-sn 2cdtco54w00 2?>Thus Xreate
  places key emphasis on domain-specific component level improvements and
  joint use of external resources. This aspect is covered in <link
  xlink:href="/w/exploitation/"><?xxe-sn 2b3f3osfk74 h?>exploitation</link>
  and <link xlink:href="/w/concepts/containers/"><?xxe-sn 2b3f3osfk74 i?>containers</link>
  chapters.</para>

  <para xlink:href="w/virtualization/"><?xxe-sn 2cdtco54w00 3?>Unlike academic
  languages, Xreate targets safe and reliable usage of effectful computations
  such as IO covered in <link xlink:href="/w/virtualization"><?xxe-sn 2b3f3osfk74 j?>virtualization</link>
  and <link xlink:href="/w/exploitation/"><?xxe-sn 2b3f3osfk74 k?>exploitation</link>
  chapters, and mutable structures covered in <link
  xlink:href="/w/communication/"><?xxe-sn 2b3f3osfk74 l?>communication</link>.</para>

  <section>
    <?xxe-sn 2b06cb2u4g0 3?>

    <title><?xxe-sn 2b06cb2u4g0 4?>Basic Example</title>

    <para><?xxe-sn 2b06cb2u4g0 5?>To demonstrate what Xreate is all about,
    basic example is given below:</para>

    <programlisting xml:id="Example_1"><?xxe-sn 2b06cb2u4g0 x?>name="tests/introduction.cpp: Introduction.Doc_Example_1", lines=15
guard::                                  iAmVeryFast 
{
  div = function(a:: float, b:: float):: float
  {
    a / b
  } 
}

guard::                                  iAmVerySafe 
{
  div = function(a:: float, b:: float):: float
  {
    if ( b == (0::float)):: float {0::float} else {a / b}
  } 
}

test = function::                        float; entry; iAmVerySecure 
{
  div(10, 5)
}</programlisting>

    <para><?xxe-sn 2b06cb2u4g0 y?>Here entry point of the program is a
    function <code><?xxe-sn 2b06cb2u4g0 z?>test</code> recognized so by
    compiler because of annotation <code><?xxe-sn 2b06cb2u4g0 10?>entry</code>
    in its signature. There are also two functions <code><?xxe-sn 2b06cb2u4g0 11?>div</code>
    called <emphasis><?xxe-sn 2b06cb2u4g0 12?>specializations</emphasis>. Each
    specialization has a guard that defines a condition that has to be met in
    order to invoke this particular specialization. In the example,
    specializations of <code><?xxe-sn 2b06cb2u4g0 13?>div</code> have
    <code><?xxe-sn 2b06cb2u4g0 14?>iAmVeryFast</code> and <code><?xxe-sn 2b06cb2u4g0 15?>iAmVerySafe</code>
    guards, respectively. Let's say that developer specifies two
    specializations where the first one is a very fast division
    implementation, while the second one is a very safe division
    implementation since it checks division by zero, although it is
    unacceptably slow due to an extra check instruction. This is a basis of
    <link xlink:href="/w/concepts/polymorphism/"><?xxe-sn 2b3f3osfk74 2?>polymorphism</link>
    — client's code <code><?xxe-sn 2b3f3osfk74 3?>test</code> is able to work
    with any specialization, and compiler must decide which one to invoke with
    the only hint it has — annotation <code><?xxe-sn 2b3f3osfk74 5?>iAmVerySecure</code>
    in the function <code><?xxe-sn 2b3f3osfk74 7?>test</code>'s
    signature.</para>

    <remark><?xxe-sn 2ccp2iy80zj 1td6aqezxvj7n?>"provides two specializations"
    - возможно, лучший вариант "designates/assigns/allocates two
    specializations". Или даже просто specifies/indicates. (PS заменил на
    specifies)</remark>

    <remark><?xxe-sn 2ccp2iy80zj 1td6aqezxvj7m?>"unbearably slow" - я бы
    заменил на более нейтральное "too slow". Unbearable - это скорее об
    ощущениях человека. Или, если под "unbearably" имеется в виду "недопустимо
    медленный", тогда - unacceptably slow.</remark>

    <note>
      <?xxe-sn 2b3f3osfk74 n?>

      <para><?xxe-sn 2b3f3osfk74 o?>All annotations (except <code><?xxe-sn 2b3f3osfk74 m?>entry</code>)
      are custom defined by developer itself.</para>
    </note>

    <para><?xxe-sn 2b3f3osfk74 6?>This is when transcend comes into play. By
    adding a transcend rule as shown below it is possible to associate
    annotation <code><?xxe-sn 2b3f3osfk74 8?>iAmVerySecure</code> with
    invocation of specialization guarded by <code><?xxe-sn 2b3f3osfk74 9?>iAmVerySafe:</code></para>

    <programlisting xml:id="Transcend_Example_1"><?xxe-sn 2b3f3osfk74 a?>name="tests/introduction.cpp: Introduction.Doc_Example_1", lines=15
dfa_callguard(SiteInv, iAmVerySafe):-
  dfa_callfn(SiteInv, div);
  SiteInv = s(_, _, ScopeInv);
  cfa_parent(ScopeInv, function(FnInv));
  bind_func(FnInv, iAmVerySecure).</programlisting>

    <para><?xxe-sn 2b3f3osfk74 b?>Transcend rules are written in ASP syntax —
    common syntax to write logic programs. This particular rule reads that for
    any function annotated with <code><?xxe-sn 2b3f3osfk74 c?>iAmVerySecure</code>,
    certain specialization <code><?xxe-sn 2b3f3osfk74 d?>iAmVerySafe</code> is
    chosen for <code><?xxe-sn 2b3f3osfk74 e?>div</code> invocation.</para>

    <note>
      <?xxe-sn 2b3f3osfk74 p?>

      <para><?xxe-sn 2b3f3osfk74 q?>In this example an appropriate
      specialization is statically resolved, so the other specialization isn't
      even compiled.</para>

      <remark><?xxe-sn 2ccp2iy80zj 1td6aqezxvj7o?>the, потому что их всего
      две.</remark>
    </note>

    <para><?xxe-sn 2b3f3osfk74 f?>By providing custom rules it is possible to
    implement any polymorphism strategy, be it performed statically or
    dynamically. The example demonstrates basic workflow: transcend gathers
    available information about a program such as annotations and using custom
    rules makes a decision to guide compilation process, particularly by
    selecting appropriate specializations as in the above example.</para>
  </section>

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

    <title><?xxe-sn 2ba2e84701s 2?>Build and Run on Linux</title>

    <para><?xxe-sn 2ba2e84701s 3?>Major dependencies:</para>

    <itemizedlist>
      <?xxe-sn 2ba2e84701s 4?>

      <listitem>
        <?xxe-sn 2ba2e84701s 5?>

        <para><?xxe-sn 2ba2e84701s 6?>gcc 7</para>
      </listitem>

      <listitem>
        <?xxe-sn 2ba2e84701s 7?>

        <para><?xxe-sn 2ba2e84701s 8?>llvm 5, clang 5</para>
      </listitem>

      <listitem>
        <?xxe-sn 2ba2e84701s 9?>

        <para><?xxe-sn 2ba2e84701s a?>boost 1.66</para>
      </listitem>

      <listitem>
        <?xxe-sn 2ba2e84701s b?>

        <para><?xxe-sn 2ba2e84701s c?>coco</para>
      </listitem>

      <listitem>
        <?xxe-sn 2ba2e84701s d?>

        <para><?xxe-sn 2ba2e84701s e?>clingo</para>
      </listitem>
    </itemizedlist>

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

    <para><?xxe-sn 2ba2e84701s p?>Pull sources directly from
    repository:</para>

    <literallayout><?xxe-sn 2ba2e84701s g?>git clone --recursive https://pgess@bitbucket.org/pgess/xreate.git</literallayout>

    <para><?xxe-sn 2ba2e84701s q?>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 2ccp2iy80zj 1td6aqezxvj7p?>"Enter into source directory"
    - тут перед directory явно нужен артикль. Гугл говорит, что определенный -
    the</remark>

    <important>
      <?xxe-sn 2cdtco54w00 4?>

      <para><?xxe-sn 2cdtco54w00 5?>Carefully inspect scripts before
      run</para>
    </important>

    <para><?xxe-sn 2ba2e84701s 13?>On <emphasis role="bold"><?xxe-sn 2ba2e84701s 14?>OpenSuse
    Leap 15</emphasis>:</para>

    <literallayout><?xxe-sn 2ba2e84701s t?>./installation/prepare-opensuse-leap15</literallayout>

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

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

    <literallayout><?xxe-sn 2ba2e84701s w?>cd build
make</literallayout>

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

    <literallayout><?xxe-sn 2ba2e84701s y?>cd ..
./build/tests/xreate-tests</literallayout>

    <note>
      <?xxe-sn 2ba2e84701s 1h?>

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

    <para><?xxe-sn 2ba2e84701s 17?>For consequent rebuilds after updates etc
    invoke <code><?xxe-sn 2ba2e84701s 18?>cmake</code> as follows:</para>

    <literallayout><?xxe-sn 2ba2e84701s 19?>#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 2ba2e84701s 1j?>Cmake's selected parameters:</para>

    <itemizedlist>
      <?xxe-sn 2ba2e84701s 1a?>

      <listitem>
        <?xxe-sn 2ba2e84701s 1b?>

        <para><?xxe-sn 2ba2e84701s 1c?>BUILD_XREATE_TESTS Determines whether
        to build tests</para>
      </listitem>

      <listitem>
        <?xxe-sn 2ba2e84701s 1d?>

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

      <listitem>
        <?xxe-sn 2ba2e84701s 1f?>

        <para><?xxe-sn 2ba2e84701s 1g?>CLINGO_PATH Installed Clingo
        directory</para>

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