Anders
Dahnielson
Romain
Behar
Timothy
M
Shead

# Installation

## Introduction

This chapter describes the installation process for various platforms.

## Installing the Win32 Binary

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 http://www.opengl.org .

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;.

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 `PATH` environment variable).

You'll need to install the GTK+ library for Win32.

&k3d; Win32 binaries are currently linked with the old DLLs (version 1.3).

Get the &k3d; binary distribution for Win32. Expand the distribution into a suitable location, say `c:\k3d` (I recommend -against- installing the program in `c:\program files` 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).

Set the `HOME` environment variable to point to your home directory. For Win95/98 users, `c:\` is probably the best choice. WinNT users should use `c:\winnt\profiles\username` where username is the username you logged-in with:

    set HOME=your home directory

Set environment variables that &k3d; requires in order to run:

    set K3D_BASE_PATH=c:/k3d
    set K3D_SHADERS_PATH=c:/k3d/shaders

Note the use of '/' not '\'.

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.

You need to add the directory containing the k3d executables (`k3d.exe`, `sdpslparse.exe`, `renderjob.exe`, and `renderframe.exe`) to your path:

    set PATH=%PATH%;c:\k3d

&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 `c:\k3d\shaders directory`, and follow the instructions included with your render engine to compile each `.sl` file.

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: http://gnuwin32.sourceforge.net/packages/netpbm.htm You will need at least:

- 'NetPBM' main package,

- 'file' tool package,

- 'jpeg', 'tiff' and 'zlib' libraries packages.

Note that you will need only `*-bin.zip` files.

Extract all archives to, say `c:\netpbm"`. Add directory with NetPBM executables to your path:

    set PATH=%PATH%;c:\netpbm\bin

Create directories `c:\Program files\files\share` then copy the directory content `c:\netpbm\bin\share` in it.

Note that `file.exe` file can be located anywhere in your `PATH` but it MUST have its "magic" files in `c:\Program Files\file\share`.

Change directory to the install directory and run &k3d; from the command-line:

    cd c:\k3d
    .\k3d

or run from anywhere

    k3d --basepath c:/k3d

## Build Source Distribution

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:

    $ ./configure --help

Once you've decided which (if any) configuration options you want to override, you can run the configure script:

    $ ./configure <options>

If you don't have plib library, just type:

    $ ./configure --without-plib

If you're working in Cygwin, you MUST use the --with-static-plugins and --disable-shared options; see below.

Assuming there were no errors, you may now build the project:

    $ make

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:

    $ make CXXFLAGS=-Wall

Similarly, depending on your architecture/compiler, you may wish to have the code optimized:

    $ make "CXXFLAGS=-Wall -O2"

If you're impatient and want to see the program run from the source tree:

    $ make test

You may optionally wish to run the standard regression test suite (recommended):

    $ make check

You're now ready to install the K-3D binaries for general use on your host. You will have to have root access:

    $ su -c "make install"

Once installation is complete, you'll need to add the K-3D "bin" directory to your PATH:

    $ export PATH=$PATH:/usr/local/k3d/bin

Now you can run K-3D:

    $ k3d

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:

    $ make doxygen

... 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.

If you want to make a copy of the K-3D source available for others, you can roll your own distribution tarball:

    $ make distcheck

## Installation Layout

On Posix operating systems the default prefix for &k3d; is `/usr/local/k3d`. 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.

&k3d; files will be installed to the following directories relative to the prefix:

      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