INSTALL

   1 Installation
   2 ============
   3
   4
   5 Prerequisites
   6 -------------
   7
   8 PyX requires Python 2.3 or newer and a TeX installation (including Type1 fonts).
   9 Try to start 'python', 'tex' and 'kpsewhich cmr10.pfb' (the latter should issue
  10 a full path of the requested Type1 font).
  11
  12
  13 Local usage without C extension modules
  14 ---------------------------------------
  15
  16 PyX can be run without any installation. To test your environment copy the file
  17 hello.py from the examples directory to the main pyx directory (where the
  18 subdirectory pyx containing the modules is located) and type 'python hello.py'.
  19 When your TeX installation isn't configured to use Type1 fonts by default, you
  20 may have to insert the line 'text.set(fontmaps="psfonts.cmz")' after the import
  21 statement and try again. See the FAQ for further details about TeX and font
  22 configuration issues.
  23
  24
  25 Installation procedure
  26 ----------------------
  27
  28 The installation of PyX is pretty straightforward if you have installed the
  29 Python distutils package.
  30
  31 First, you have to decide which C extension modules you want to build. This can
  32 be done by setting the respective flags in the setup.cfg config file. By default
  33 no C extension modules are built and appropriate fallbacks will be used instead.
  34
  35 The build_t1code option enables building of an extension module, which enables
  36 faster coding/decoding of Type 1 fonts. The only requisites for building this
  37 module are the Python header files and a C compiler. Note that the C compiler
  38 has to suit the Python distribution you are using.
  39
  40 The second extension module pykpathsea provides Python binding for the kpathsea
  41 library, which enables fast searching for files in the TeX/LaTeX directory
  42 hierarchy. You will need the header files of this library, which unfortunately
  43 are not included in many standard TeX distributions. Note that the fallback,
  44 which uses the kpsewhich program, works equally well, although it is not as
  45 efficient as using the library directly. If you want to build the C extension
  46 module, you may also have to specify the location of the kpathsea header files
  47 and of the library itself in the setup.cfg file.
  48
  49 After you have adapted the setup.cfg file to your needs, you can either build
  50 the extension modules locally by running
  51
  52     python setup.py build_ext -i
  53
  54 or install PyX system wide by using
  55
  56     python setup.py install
  57
  58 or an appropriate variant thereof.
  59
  60
  61 For Mac OS X users
  62 ------------------
  63
  64 A complete install of the TeX i-Package (http://ii2.sourceforge.net/) contains
  65 the kpathsea library. The include files and the library itself can be found in
  66 /usr/local/teTeX/include and /usr/local/teTeX/lib, respectively. These
  67 directories should be indicated in the setup.cfg file.
  68
  69
  70 Path setup when installing to a non-standard directory layout
  71 -------------------------------------------------------------
  72
  73 PyX places shared data in the directory <install-dir>/share/pyx and the system
  74 wide configuration in the file <root>/etc/pyxrc. <install-dir> and <root> are
  75 options to the distutils install-data command. See the distutils documentation
  76 for details. The final path information is stored in siteconfig.py. While the
  77 original siteconfig.py calculates the positions relative to its current
  78 position thus enabling local usage, during install a proper siteconfig.py will
  79 be created.
  80
  81 To install the complete package at some other place, say /tmp, use the command
  82
  83     python setup.py install --root=/tmp --install-data=/ --install-lib=/
  84
  85 You can then tell python to use this installation by
  86
  87     import sys
  88     sys.path.insert(0, "/tmp")
  89
  90 or by adjusting your PYTHONPATH environment variable.
  91
  92
  93 Compiling the manual
  94 --------------------
  95
  96 For the layout of the manual we have made use of the standard Python
  97 documentation framework. For building the manual, you will need the script
  98 "mkhowto" of your Python distribution. Please make a soft-link of this script
  99 into the manual directory
 100
 101     cd manual/
 102     ln -s </usr/lib/>python/doc/tools/mkhowto mkhowto
 103     make
 104
 105 Note that this requires Python version 2.3 and above. When using older Python
 106 versions you need to get the Python documentation sources separately from
 107 http://www.python.org/ and try to find the script there. Alternatively you may
 108 download the manual from the PyX homepage at http://pyx.sourceforge.net/.