z-chap1.xml

<Chapter Label="Installing Digraphs">
  <Heading>Installing &Digraphs;</Heading>

  <Section Label="For those in a hurry">
    <Heading>For those in a hurry</Heading>
    In this section we give a brief description of how to start using
    &Digraphs;.<P/>

    It is assumed that you have a working copy of &GAP; with version number
    &GAPVERS; or higher. The most up-to-date version of &GAP; and instructions
    on how to install it can be obtained from the main &GAP; webpage
    <URL>https://www.gap-system.org</URL>.<P/>

    The following is a summary of the steps that should lead to a
    successful installation of &Digraphs;:

    <List>

      <Item>
        ensure that the &IO; package version &IOVERS; or higher is available.
        &IO; must be compiled before &Digraphs; can be loaded.
      </Item>

      <Item>
        ensure that the &ORB; package version &ORBVERS; or higher is available.
        &ORB; has better performance when compiled, but although compilation is
        recommended, it is not required to be compiled for &Digraphs; to be
        loaded.
      </Item>

      <Item> ensure that the &DATASTRUCTURES; package version
        &DATASTRUCTURESVERS; or higher is available. 
    </Item>

      <Item>
        <B>This step is optional:</B> certain functions in &Digraphs; require
        the &GRAPE; package to be available; see Section
        <Ref Subsect="The Grape package"/> for full details.  To use these
        functions make sure
        that the &GRAPE; package version &GRAPEVERS; or higher is available.
        If &GRAPE; is not available, then &Digraphs; can be used as normal with
        the exception that the functions listed in Subsection
        <Ref Subsect="The Grape package"/> will not work.
      </Item>
      
      <Item>
        <B>This step is optional:</B> certain functions in &Digraphs; require
          the &NautyTracesInterface; package to be available.
        <!-- TODO 
          see Section
        <Ref Subsect="The Grape package"/> for full details.  -->
        If you want to make use of these functions, please ensure that the
        &NautyTracesInterface; package version &NAUTYTRACESINTERFACEVERS; or
        higher is available.  If &NautyTracesInterface; is not available,
        then &Digraphs; can be used as normal with the exception that 
          functions whose names contain <Q>Nauty</Q> will not work.
      </Item>

      <Item>
        download the package archive <F>&ARCHIVENAME;.tar.gz</F> from
        <URL Text="the Digraphs package webpage">https://digraphs.github.io/Digraphs/</URL>.
      </Item>

      <Item>
        unzip and untar the file, this should create a directory called
        <F>&ARCHIVENAME;</F>.
      </Item>

      <Item>
        locate the <F>pkg</F> directory of your &GAP; directory, which contains
        the directories <F>lib</F>, <F>doc</F> and so on. Move the directory
        <F>&ARCHIVENAME;</F> into the <F>pkg</F> directory.
      </Item>

      <Item>
        it is necessary to compile the &Digraphs; package.
        Inside the <F>pkg/&ARCHIVENAME;</F> directory, type
        <Listing>
<![CDATA[./configure
make]]></Listing>
        Further information about this step can be found in Section
        <Ref Sect="Compiling the kernel module"/>.
      </Item>

      <Item>
        start &GAP; in the usual way (i.e. type <C>gap</C> at the command line).
      </Item>

      <Item>
        type <C>LoadPackage("digraphs");</C>
      </Item>
    </List>

    If you want to check that the package is working correctly, you
    should run some of the tests described in Section
    <Ref Sect="Testing your installation"/>.
    <Subsection Label="Configuration options">
      <Heading>Configuration options</Heading>

In addition to the usual autoconf generated configuration flags, the following
flags are provided.

<Table Align="|l|l|">
 <Caption>Configuration flags</Caption>
 <HorLine/>
  <Row>
   <Item>Option</Item><Item>Meaning</Item>
  </Row>
 <HorLine/>
 <HorLine/>
 <Row>
   <Item><C>--enable-code-coverage</C></Item><Item> enable code coverage support</Item>
 </Row>
 <Row>
   <Item><C>--enable-compile-warnings</C></Item><Item> enable compiler warnings</Item>
 </Row>
 <Row>
   <Item><C>--enable-debug</C></Item><Item> enable debug mode</Item>
 </Row>
 <Row>
   <Item><C>--with-external-bliss</C></Item><Item> use external &BLISS;</Item>
 </Row>
 <Row>
   <Item><C>--with-external-planarity</C></Item><Item> use external &EDGE_PLANARITY_SUITE;</Item>
 </Row>
 <Row>
   <Item><C>--with-gaproot</C></Item><Item> specify root of GAP installation</Item>
 </Row>
 <Row>
   <Item><C>--without-intrinsics</C></Item><Item> do not use compiler intrinsics even if available</Item>
 </Row>
 <HorLine/>
</Table>
</Subsection>
  </Section>

  <!--**********************************************************************-->
  <!--**********************************************************************-->

  <Section Label="Optional package dependencies">
    <Heading>Optional package dependencies</Heading>

    <!--********************************************************************-->

    The &Digraphs; package is written in &GAP; and C code and requires the
    &IO; package.  The &IO; package is used to read and write transformations,
    partial permutations, and bipartitions to a file. <P/>

    <!--********************************************************************-->

    <Subsection Label="The Grape package">
      <Heading>The Grape package</Heading>

      The &GRAPE; package must be available for the following operations to be
      available:

      <List>
        <Item><Ref Oper="Graph"/> with a digraph argument</Item>
        <Item><Ref Attr="AsGraph"/> with a digraph argument</Item>
        <Item><Ref Oper="Digraph"/> with a &GRAPE; graph argument</Item>
      </List>

      If &GRAPE; is not available, then &Digraphs; can be used as normal with
      the exception that the functions above will not work.
    </Subsection>
  </Section>

  <!--**********************************************************************-->
  <!--**********************************************************************-->

  <Section Label="Compiling the kernel module">
    <Heading>Compiling the kernel module</Heading>
    The &Digraphs; package has a &GAP; kernel component in
    C which should be compiled. This component contains certain low-level
    functions required by &Digraphs;.
    <P/>

    It is not possible to use the &Digraphs; package without compiling it.<P/>

    To compile the kernel component inside the <F>pkg/&ARCHIVENAME;</F>
    directory, type
<Listing>
<![CDATA[
./configure
make]]></Listing>
    <P/>

    If you installed the package in another 'pkg' directory than the standard 'pkg'
    directory in your &GAP; installation, then you have to do two things. Firstly
    during compilation you have to use the option '--with-gaproot=PATH' of the
    'configure' script where 'PATH' is a path to the main GAP root directory (if
    not given the default '../..' is assumed).<P/>

    If you installed &GAP; on several architectures, you must execute the
    configure/make step for each of the architectures. You can either do this
    immediately after configuring and compiling GAP itself on this architecture, or
    alternatively set the environment
    variable 'CONFIGNAME' to the name of the configuration you used when compiling
    GAP before running './configure'.  Note however that your compiler choice and
    flags (environment variables 'CC' and 'CFLAGS') need to be chosen to match the
    setup of the original GAP compilation. For example you have to specify 32-bit
    or 64-bit mode correctly!
  </Section>

  <!--**********************************************************************-->
  <!--**********************************************************************-->

  <Section Label="Rebuilding the documentation">
    <Heading>Rebuilding the documentation</Heading>
    The &Digraphs; package comes complete with pdf, html, and text versions of
    the documentation. However, you might find it necessary, at some point, to
    rebuild the documentation. To rebuild the documentation, please use the
    function <Ref Func="DigraphsMakeDoc"/>.

    <#Include Label="DigraphsMakeDoc">
  </Section>

  <!--**********************************************************************-->
  <!--**********************************************************************-->

  <Section Label="Testing your installation">
    <Heading>Testing your installation</Heading>

    In this section we describe how to test that &Digraphs; is working as
    intended.  To test that &Digraphs; is installed correctly use
    <Ref Func="DigraphsTestInstall"/> or for more extensive tests use
    <Ref Func="DigraphsTestStandard"/>. <P/>

    If something goes wrong, then please review the instructions in Section <Ref
      Sect="For those in a hurry"/> and ensure that &Digraphs; has been
    properly installed.  If you continue having problems, please use the <URL
      Text="issue tracker">https://github.com/digraphs/Digraphs/issues</URL>
    to report the issues you are having.

    <#Include Label="DigraphsTestInstall">
    <#Include Label="DigraphsTestStandard">
    <#Include Label="DigraphsTestExtreme">

  </Section>

  <!--**********************************************************************-->
  <!--**********************************************************************-->


</Chapter>