doc/parts/install/index.sxml

   1 <?xml version="1.0" encoding="UTF-8"?>
   2 <!--#include virtual="../formats/doctype-book.xml" meta="yes" -->
   3
   4 <book>
   5         <title>Installing <str-Shapes /></title>
   6         <description>
   7                 <p>Instructions on how to install <str-Shapes />.</p>
   8         </description>
   9         <meta-selflink><part-href name="install" /></meta-selflink>
  10         <examples-home href=<!--#expand-next-string-->"$(EXAMPLES)" />
  11         <top>
  12                 <p><str-Shapes /> is written to be as platform independent as   possible, but the system is developed on Macintosh and Linux and has not been tested under Windows.  As a concequence, the instructions given here might need to be adjusted in order to get <str-Shapes /> running in Windows.</p>
  13
  14         <p>This install guide will guide you obtaining shapes, making sure all dependencies are available, and finally compile and install the program.</p>
  15         </top>
  16
  17         <section id="install-fetch">
  18         <title>Download the source</title>
  19         <body>
  20                 <p>The source code can be downloaded from the <a href="http://www.control.isy.liu.se/~tidefelt/projects/shapes/download/">download</a> section of the <str-Shapes /> homepage.  The source is available in files named <filename>shapes-x-y-z.tar.gz</filename>, where a change in <filename>z</filename> is a pure bug fix with out new functionality, whereas a change in <filename>y</filename> should be only backwards compatible feature fixes, and finally <filename>x</filename> is used to indicate backwards incompatible changes.</p>
  21         </body>
  22         </section><!-- End of install-fetch -->
  23
  24         <section id="install-depend">
  25         <title>Dependencies</title>
  26         <top>
  27                 <p>In order to build the <str-Shapes /> compiler from the downloaded source, the following software need to be installed on your system:</p>
  28         </top>
  29
  30         <section id="install-depend/required">
  31         <title>Required</title>
  32         <body>
  33                 <p>These libraries needs to be present on your computer in order to install <str-Shapes />:</p>
  34                 <ul>
  35                         <li><p><em>zlib</em>, the compression library.  The source and install instructions can be obtained from the <a href="http://www.gzip.org/zlib/"><em>zlib</em> homepage</a>.</p></li>
  36                         <li><p>The <em>GNU libiconv</em> library, for conversions between various character encodings.  Refer to the <a href="http://www.gnu.org/software/libiconv/">library homepage</a> to get the software.</p></li>
  37                         <li><p>The GNU Scientific Library (<em>GSL</em>) v 1.8 or later, for mathematical algorithms.  Obtain <em>GSL</em> from its <a href="http://www.gnu.org/software/gsl/">homepage</a>.</p></li>
  38                 </ul>
  39         </body>
  40         </section><!-- End of install-depend/required -->
  41
  42         <section id="install-depend/recommended">
  43         <title>Recommended (optional)</title>
  44         <body>
  45                 <p>A working <str-LaTeX /> installation is optional, but to produce labels with beautifully formated math you need it.</p>
  46                 <ul>
  47                         <li><p><em><str-LaTeX /></em>, the typesetting language.  There are many <str-TeX /> distributions available, one free and suitable is <str-TeX /> Live, download the latest <str-TeX /> Live distribution form <a href="http://www.tug.org/texcollection/">tug.org</a>.</p></li>
  48                 </ul>
  49         </body>
  50         </section><!-- End of install-depend/recommended -->
  51         </section><!-- End of install-depend -->
  52
  53
  54 <section id="install-build">
  55 <title>Building and installing</title>
  56 <body>
  57 <p>Assuming the downloaded file was called <filename>shapes-x-y-z.tar.gz</filename>, the standard procedure below contains the necessary steps.</p>
  58 <command-line>
  59 tar zxf shapes-x-y-z.tar.gz
  60 cd shapes-x-y-z
  61 ./configure
  62 make
  63 make check
  64 sudo make install
  65 </command-line>
  66 <p>You may omit the <quote>make check</quote> part if you like, but it won't save you much time.  Also, the <quote>sudo</quote> word at the beginning of the last line may not be appropriate for your system, or not required if the installation was configured to install somewhere where your user has permission to write files.</p>
  67 <p>To see for yourself that the program is installed, run</p>
  68 <command-line>
  69 shapes --version
  70 </command-line>
  71 <p>and shapes should reply with just installed version of <str-Shapes />.  You can also try to view the online help:</p>
  72 <command-line>
  73 man shapes
  74 </command-line>
  75 </body>
  76 </section><!-- End of install-fetch -->
  77
  78
  79 <section id="install-dev">
  80 <title>Help develop <str-Shapes /></title>
  81 <body>
  82         <p>To help out develop <str-Shapes /> some more packages are needed, depending on which part of <str-Shapes /> you are interested in, you need different tools as outlined below.  Any and all improvements are very welcome and should be sent by e-mail to <a href="mailto:tidefelt@isy.liu.se">tidefelt@isy.liu.se</a>.</p>
  83
  84         <p>First you should get a hold of the very latest version of the <str-Shapes /> soure.  To do this you need to use <em>git</em>.
  85         <ul>
  86                 <li><p><em>git</em>, used to manage <str-Shapes />.  Get <em>git</em> from <a href="http://git.or.cz">git homepage</a>.</p></li>
  87         </ul>
  88         With <em>git</em> installed, <str-Shapes /> can be cloned from <tt>URL_TO_BE_DECIDED</tt>.</p>
  89
  90         <p>To further compile the obtained source, the <em>GNU Autoconf-Automake-Libtool</em> toolchain is needed in combination with <em>Flex</em> and <em>Bison</em>
  91         <ul>
  92                 <li><p><em>GNU Automake</em> can be obtained from <a href="http://www.gnu.org/software/automake/">GNU's homepage</a>.</p></li>
  93                 <li><p><em>GNU Autoconf</em> can be downloaded from its <a href="http://www.gnu.org/software/autoconf/">homepage</a>.</p></li>
  94                 <li><p><em>GNU Libtool</em> (GNU Portable Library Tool) is available from <a href="http://www.gnu.org/software/libtool/">GNU</a>.</p></li>
  95                 <li><p><em>Bison 2.3</em>, needed only if you want to change the way <str-Shapes /> parse source code.  Obtain a current verson of <em>Bison</em> from <a href="http://www.gnu.org/software/bison/">GNU</a>.</p></li>
  96                 <li><p><em>Flex 2.5.33</em>, needed to modify the scanners used by <str-Shapes />.  Download a sufficiently new version of <em>Flex</em> from <a href="http://flex.sourceforge.net">Sourceforge</a>.</p></li>
  97         </ul>
  98         </p>
  99
 100         <p>To run the <str-Shapes /> test suit, <tt>convert</tt> from <em>ImageMagick</em> is needed.to compare the generated images.
 101         <ul>
 102                 <li><p><em>ImageMagick 6.4.0</em>, download it from <a href="http://imagemagick.org">here</a>.</p></li>
 103         </ul>
 104         </p>
 105
 106         <p><em>Saxon</em> is used to transform the documentation from the XML format it is written in to man-pages and <str-HTML />.  In this process <em>ImageMagick</em> is used too.
 107         <ul>
 108                 <li><p><em>Saxon 9.0.0.2</em>, is available from its homepage at <a href="http://saxon.sourceforge.net">Sourceforge</a>.</p></li>
 109         </ul>
 110         </p>
 111 </body>
 112 </section><!-- End of install-dev -->
 113 </book>