<chapter id="Installation">
<chapterinfo>
<author><firstname>Anders</firstname> <surname>Dahnielson</surname></author>
<author><firstname>Romain</firstname> <surname>Behar</surname></author>
<author><firstname>Timothy</firstname> <othername role="mi">M</othername> <surname>Shead</surname></author>
</chapterinfo>

<title>Installation</title>

<sect1>
<title>Introduction</title>
<para>
This chapter describes the installation process for various platforms.
</para>
</sect1>

<sect1 id="InstallWin32Binary">
<title>Installing the Win32 Binary</title>
<para>
Make sure you have OpenGL installed on your system. If you use Windows 98 or
Windows NT 4.0 you already have it. If you have a very early version of Windows 95,
you may need to download it from <ulink url="http://www.opengl.org">http://www.opengl.org</ulink> .
</para>
<para>
You'll need a render engine to convert your virtual worlds into images.
&k3d; sends its output to rendering engines using the Pixar Renderman Interface, so
you can use &k3d; with any RI-compliant rendering engine. Aqsis and BMRT are
excellent choices, but there are many others - see the list of engines known to work
with &k3d;.
</para>
<para>
Install the render engine of your choice, and verify that it can be run by hand
from the command-line (at a minimum, you'll have to update your <envar>PATH</envar> environment variable).
</para>
<para>
You'll need to install the GTK+ library for Win32.
</para>
<important>
<para>&k3d; Win32 binaries are currently linked with the old DLLs (version 1.3).</para>
</important>
<para>
Get the &k3d; binary distribution for Win32. Expand the distribution into a suitable 
location, say <filename>c:\k3d</filename> (I recommend -against- installing the program 
in <filename>c:\program files</filename> because you will have to do some command-line 
work to get the program running, and the space in "program files" is an endless source 
of trouble).
</para>
<para>
Set the <envar>HOME</envar> environment variable to point to your home directory.  
For Win95/98 users, <filename>c:\</filename> is probably the best choice.  WinNT 
users should use <filename>c:\winnt\profiles\username</filename>  where username 
is the username you logged-in with:
</para>
<programlisting>
set HOME=your home directory
</programlisting>
<para>
Set environment variables that &k3d; requires in order to run:
</para>
<programlisting>
set K3D_BASE_PATH=c:/k3d
set K3D_SHADERS_PATH=c:/k3d/shaders
</programlisting>
<note>
<para>Note the use of '/' not '\'.</para>
</note>
<note>
<para>Note to set an environment varialbe on Windows 2000, select Start/Settings/Control Panel/System, 
then go to the advanced pane and click 'Environment Variables'. The path entry (set below) is in 
the top list.</para>
</note>
<para>
You need to add the directory containing the k3d executables (<filename>k3d.exe</filename>, 
<filename>sdpslparse.exe</filename>, <filename>renderjob.exe</filename>, and 
<filename>renderframe.exe</filename>) to your path:
</para>
<programlisting>
set PATH=%PATH%;c:\k3d
</programlisting>
<para>
&k3d; now compiles shaders on demand - when render engine is started. If you have an older version, 
you'll have to manually compile the shaders included with &k3d; so they'll work with your render 
engine.  cd into the <filename>c:\k3d\shaders directory</filename>, and follow the instructions 
included with your render engine to compile each <filename>.sl</filename> file.
</para>
<para>
You'll have to install NetPBM tools to play with bitmaps and textures. NetPBM for win32
implementation (and may usefull tools too) you can find at: 
<ulink url="http://gnuwin32.sourceforge.net/packages/netpbm.htm">http://gnuwin32.sourceforge.net/packages/netpbm.htm</ulink>
You will need at least:
</para>
<itemizedlist>
<listitem><para>'NetPBM' main package,</para></listitem>
<listitem><para>'file' tool package,</para></listitem>
<listitem><para>'jpeg', 'tiff' and 'zlib' libraries packages.</para></listitem>
</itemizedlist>
<note>
<para>Note that you will need only <filename>*-bin.zip</filename> files.</para>
</note>
<para>
Extract all archives to, say <filename>c:\netpbm"</filename>.
Add directory with NetPBM executables to your path:
</para>
<programlisting>
set PATH=%PATH%;c:\netpbm\bin
</programlisting>
<para>
Create directories <filename>c:\Program files\files\share</filename> then copy the directory content
<filename>c:\netpbm\bin\share</filename> in it.
</para>
<note>
<para>Note that <filename>file.exe</filename> file can be located anywhere in your <envar>PATH</envar> but 
it MUST have its "magic" files in <filename>c:\Program Files\file\share</filename>.</para>
</note>
<para>
Change directory to the install directory and run &k3d; from the command-line:
</para>
<programlisting>
cd c:\k3d
.\k3d
</programlisting>
<para>
or run from anywhere
</para>
<programlisting>
k3d --basepath c:/k3d
</programlisting>
</sect1>

<sect1 id="BuildSourceDistribution">
<title>Build Source Distribution</title>
<para>
First you need to configure it for your system.  Note that the default install 
prefix is "/usr/local/k3d".  You can obtain a listing of available configuration 
options by doing:
</para>
<programlisting>
$ ./configure --help
</programlisting>
<para>
Once you've decided which (if any) configuration options you want to override, you
can run the configure script:
</para>
<programlisting>
$ ./configure &lt;options&gt;
</programlisting>
<note>
<para>If you don't have plib library, just type:</para>
</note>
<programlisting>
$ ./configure --without-plib
</programlisting>
<note>
<para>If you're working in Cygwin, you MUST use the --with-static-plugins and
--disable-shared options; see below.</para>
</note>
<para>
Assuming there were no errors, you may now build the project:
</para>
<programlisting>
$ make
</programlisting>
<para>
Alternate: as of this writing, the K-3D makefiles generate binaries with debugging
support and no optimizing.  If you aren't a developer and don't plan to run the
program with a debugger, you can significantly decrease build-times and the size of
binaries by disabling debugging at compile-time:
</para>
<programlisting>
$ make CXXFLAGS=-Wall
</programlisting>
<para>
Similarly, depending on your architecture/compiler, you may wish to have the code
optimized:
</para>
<programlisting>
$ make "CXXFLAGS=-Wall -O2"
</programlisting>
<para>
If you're impatient and want to see the program run from the source tree:
</para>
<programlisting>
$ make test
</programlisting>
<para>
You may optionally wish to run the standard regression test suite (recommended):
</para>
<programlisting>
$ make check
</programlisting>
<para>
You're now ready to install the K-3D binaries for general use on your host.  You will
have to have root access:
</para>
<programlisting>
$ su -c "make install"
</programlisting>
<para>
Once installation is complete, you'll need to add the K-3D "bin" directory to your PATH:
</para>
<programlisting>
$ export PATH=$PATH:/usr/local/k3d/bin
</programlisting>
<para>
Now you can run K-3D:
</para>
<programlisting>
$ k3d
</programlisting>
<para>
If you're interested in contributing to K-3D, you'll want to browse through the source.
The K-3D source is annotated for the doxygen source-code documentation tool, so,
if you have doxygen installed on your system (many distributions already include it),
you can do:
</para>
<programlisting>
$ make doxygen
</programlisting>
<para>
... which will build HTML source-code documentation in the docs/doxygen/html directory.
Point a browser to docs/doxygen/html/index.html to see annotated, cross-referenced
source-code with comments.
</para>
<para>
If you want to make a copy of the K-3D source available for others, you can roll your
own distribution tarball:
</para>
<programlisting>
$ make distcheck
</programlisting>
</sect1>

<sect1 id="InstallationLayout">
<title>Installation Layout</title>
<para>
On Posix operating systems the default prefix for &k3d; is <filename>/usr/local/k3d</filename>.  This
location was chosen as a convenience for developers to avoid conflicts with the normal installation
directories for packaged software.  People creating &k3d; packages for specific OS distributions
should override the default(s) to install &k3d; wherever appropriate for their distribution.
</para>

<para>
&k3d; files will be installed to the following directories relative to the prefix:
</para>
<synopsis>
  bin/                        -- Contains the &k3d; binaries
  include/
    k3d/                      -- The &k3d; SDK header files, for plugin authors and embedders
  lib/                        -- Core &k3d; libraries including the SDK libraries
    k3d/                      -- &k3d; plugin modules that ship with the main program
  man/                        -- Man pages
  share/
    k3d/
      desktop/                -- Files for integrating &k3d; with desktops (links)
      dialogtemplates/        -- Dialog template files that define the &k3d; UI (deprecated)
      doc/
        developer_guide/      -- &k3d; developer documentation
	user_reference/       -- &k3d; user documentation (this document)
      icons/                  -- &k3d; icons for desktop use
      scripts/                -- Sample &k3d; scripts
      shaders/                -- RenderMan shaders that ship with &k3d;
      tutorials/              -- &k3d; tutorials that ship with the main program
    
</synopsis>
</sect1>

</chapter>