
Installing Skencil
==================

These installation instructions are divided into two parts. The first
part describes the third party software you need for Skencil. The second
part describes the installation of Skencil itself.

If you habe installed Skencil before you might want to go directly to the
Skencil specific instructions.

If you are installing on GNU/Linux, check the Skencil website
for uptodate notes for your platform and availability of prebuild binaries.


Installing the third party software
===================================


1. Install Tcl/Tk
-----------------

All Tcl/Tk version newer than Tcl 7.6 and Tk 4.2 should work.
Most GNU/Linux distributions include Tcl/Tk so this step should be easy.
Tcl/Tk can be found at
<http://www.scriptics.com/software/download.html>

Skencil uses only standard Tk features. No additional packages are required.


2. Install Python
-----------------

Python is available from its WWW home page: <http://www.python.org/> or
via ftp from <ftp://ftp.python.org/pub/python/>. See Python's
documentation for installation instructions.

You need at least version 1.5.1. Version 1.5 or older will not work,
since Skencil uses some features only provided by 1.5.1 or higher.

When configuring Python, be sure to enable the Tkinter module (Python's
installation instructions tell you how to do that). It is disabled by
default. Tkinter is Python's standard Tk interface.

It may be a good idea to check whether Tkinter works by running some of
the example scripts from Python's Demo/tkinter/* subdirectories.



3. Install the Python Imaging Library (PIL)
-------------------------------------------

This library is available from <http://www.pythonware.com>. See the
accompanying documentation for installation instructions. The
installation instructions of PIL versions 1.0b1 and earlier seem to
state that you have to build PIL in the Python source tree; this is not
true, you can build them anywhere you like if you have a complete Python
installation.

The installation instructions have a section describing how to add it to
tkinter. Skencil doesn't need this, as it uses its own image rendering
code. It does no harm to do it, though.

One point not mentioned in the PIL installation instructions are the
headerfiles (.h files). For easier configuration of Skencil I recommend
to install the files the following files found the libImaging
subdirectory into a directory under the Python include directory:

     ImConfig.h  ImPlatform.h  Imaging.h

(e.g. if your Python include directory is /usr/include/python1.5, put
them into /usr/include/python1.5/Extensions)

At the moment I use release 1.0 (older versions should also work).



4. Optional: Python XML package
-------------------------------

This step is optional. The XML package is only needed by the SVG import
filter. If you don't know what XML is or SVG, just skip this step. It is
not needed for normal use of Skencil.

If you want to test the SVG import filter, you can get the source of the
XML package at: http://www.python.org/topics/xml/download.html




Installing Skencil
==================

There are two ways to install Skencil.  The recommended one is to use
setup.py, a script that configures, builds and installs Skencil for you.
For cases where this script does not work, you can also use the a manual
way, described as method 2 below.

The installation process consists of three steps: configuration,
compilation and installation. These steps are quite independend from
each other, so even if the script doesn't work for one step it might
still work for the other two.


Method 1: setup.py
==================

Skencil comes with a script setup.py that can be used to configure, build
and install Skencil on your System. The normal way to invoke this script
is:

    $ ./setup.py <command> [options...]

where <command> is either 'configure', 'build' or 'install'. The command
may be followed by options, described below. 'setup --help' prints a
help message.

If you're familiar with Python, you may note that this is similar to the
setup.py scripts of the Python distutils.  This script is somewhat
different, though, because it was written before distutils existed.  The
distutils were already being discussed, however, and this script is
follows what was being discussed back then, to an extent.


Configuration
-------------

Skencil needs to access the Python Imaging Library from C, so it needs to
know where its headerfiles are. Unfortunately there's no standard place
where they are installed, but if you've installed them as described
under 'Install PIL' above, you can just do:

    $ ./setup.py configure

If your PIL headerfiles are somewhere else, use

    $ ./setup.py configure --imaging-include=<dir>

where <dir> is the appropriate directory.

Another option you may want to use is '--with-nls' to enable national
language support. If you've set the environment variable LANG to a
suitable value (e.g. de for German) Skencil uses that language in its
menus, dialogs and messages, if Skencil has the appropriate translation.



Compilation
-----------

This is simple, if configuration was successful. Just do

    $ ./setup.py build

This compiles the C-modules.


Installation
------------

setup.py installs almost all files under <prefix>/lib/sketch-<version>.

<prefix> defaults to /usr/local and <version> is the current Skencil
version. 

It also creates two symbolic links (skencil and sk2ps) in <prefix>/bin
pointing to skencil.py and sk2ps.ps in <prefix>/lib/sketch-<version>.

To install under /usr/local run

    $ ./setup.py install

to use a different <prefix> run

    $ ./setup.py install --prefix=<dir>


You can now start Skencil with 

    $ skencil

if <prefix>/bin and is in your $PATH. If it isn't, use the full filename
of the symbolic link in the <prefix>/bin directory.




Method 2: The old manual Method
===============================


First, change into the subdirectory Pax. You'll find a file Setup.in.
Copy that file to Setup and edit it. Follow the comments in that file.
Pax has to be linked against the same versions of Tcl/Tk as Tkinter.

Now, in Pax, type:

     $ make -f Makefile.pre.in boot
     $ make

You should have a file Pax/paxmodule.so now.

Now, go to the Filter subdirectory (there's another Setup.in file here,
but you shouldn't need to change it) and type:

     $ make -f Makefile.pre.in boot
     $ make

You should have a file streamfilter.so now.

Now, go to the Sketch/Modules subdirectory and edit the file Setup.in
there. Again, if you change anything, save the file as Setup.

Now, in Sketch/Modules type (you guessed it):

     $ make -f Makefile.pre.in boot
     $ make

You should have a file _sketchmodule.so now (and some other .so files).

Finally, go to the topmost directory and run the python script
finishinst.py. This will compile the Python source files. This step is
not really necessary, but sketch should start a bit faster)


Starting Skencil
================


Now you can test Skencil from the topmost directory by running

     $ python skencil.py

or

     $ ./skencil.py

if your Python interpreter is somewhere in your $PATH.


If you want to install Skencil somewhere outside of the source tree, use
the setup.py script as described above.

For further information on Skencil, have a look at the ``User's Guide'',
or if you're interested how Skencil is implemented or if you want to
extend it, read the ``Developer's Guide''. Both documents are quite
incomplete.

