This is the free-as-in-freedom K-3D 3D modeling, animation, and rendering system.

K-3D switched to a GNU autoconf/automake based build/install system in October, 2001.
Following are basic instructions for building and installing the program.

Topics:

* BINARY INSTALLATION
  - INSTALLING THE UNIX K-3D BINARY (upcoming...)
  - INSTALLING THE WIN32 K-3D BINARY

* BUILDING K-3D FROM SOURCE
  - POSIX BUILD
  - WIN32 MINGW BUILD
  - WIN32 CYGWIN/XFREE86 BUILD

* GET K-3D SOURCE FILES DIRECTLY FROM CVS

Note: there is a bug with autoconf versions 2.50 and 2.51, please use
      latest versions (>= 2.52)


---------------


INSTALLING THE WIN32 K-3D 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.
K-3D sends its output to rendering engines using the Pixar Renderman Interface, so
you can use K-3D 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 K-3D.

* 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 ... K-3D Win32 binaries are currently
linked with the old DLLs (version 1.3), TODO : INDICATE SOURCE

* Get the K-3D binary distribution.

* 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 K-3D requires in order to run:

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

Note1: the use of '/' not '\'.

Note2: 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, & renderframe.exe) to your path:

	set PATH=%PATH%;c:\k3d

* K-3D 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 K-3D
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

There are links for main NetPBM site (docs, etc.) and for download page.
You will need at least:

	'NetPBM' main package,
	'file' tool package,
	'jpeg', 'tiff' and 'zlib' librarys packages. 

Note: 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. (copy -r c:\netpbm\bin\share\* "c:\Program files\files\share").

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

* cd into the install directory and run K-3D from the command-line:

	cd c:\k3d
	.\k3d

or run from anywhere

	k3d --basepath c:/k3d



POSIX BUILD:
============

* CVS ONLY: Generated files (e.g. configure, Makefile.in) are not stored in CVS; if you are
building FROM CVS ONLY, you need to generate these files from the
top-level directory:

	$ ./bootstrap

* Now (regardless of where how you obtained the source), 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>

Note1: if you don't have plib library, just type:

	$ ./configure --without-plib

Note2: 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



WIN32 BUILD:
============

There are now two ways to build K-3D for legacy operating systems using 100%
free-as-in-freedom software; there are pros & cons with each:

* MinGW - Using MinGW (a port of gcc designed for building Win32 applications), and a
special makefile, you can build K-3D and link it against a specially-ported version of
GTK+ that uses Win32 GDI for drawing instead of xlib.  Pros: less setup to create a build
environment, better runtime UI responsiveness with GTK+ using "native" drawing.
Cons: GTK+ Win32 port does not provide 100% of native GTK+ functionality. 

* Cygwin / XFree86 - Using Cygwin to provide a Posix shell environment and XFree86 to
provide an X server, you can build K-3D using the same autoconf/automake build system
used for the majority of its development.  Pros: same build process, codepath, and
functionality as native K-3D.  Less work keeping up-to-date over the long run.  Cygwin
and XFree86 are extremely well supported.   Cons: extra layer of abstraction in X affects
UI performance.  More work to get going initially. 


WIN32 MINGW BUILD:
==================

1. Tools

MinGW 2.0 available from http://www.mingw.org. This is an self-extracting archive 
of the current development tools for MinGW packed into a simple installation. Run that
exe archive end install MinGW to a suitable directory, I will presume c:\mingw 
for the remainder of these instructions.

MSYS available from the same MinGW site. This is a suite of Un*x like
tools for Windows, giving the functionality of things like sh, gawk, etc. Run MSYS 
self-extracting archive and install this to a suitable directory. MSYS installer
recommend c:\msys\1.0.

MsysDTK package - also form MinGW site - contains additional Unix-like tools 
e.g. automake, autoconf, etc necessary to run 'configure' scripts. Again msysDTK
installer suggests c:\msys\1.0.

Also highly recommended are installations of any updates (e.g. gcc, binutils).
Just look at package(s) release date at download page.


You will need to make sure that c:\mingw\bin and c:\msys\1.0\bin are available
from your path, quite early on in the search paths to make sure that the MinGW version
of various tools are found. This can be accomplished by creating a batch file to
initialise a MinGW build environment, something like:

	@echo off
	set PATH=c:\mingw\bin;c:\msys\1.0\bin;%PATH%
	cmd

2. Additional requirements

Freetype2 library available from the same download page as NetPBM tools
	http://gnuwin32.sourceforge.net/packages/netpbm.htm
You will need development archive (necessary for k3d compilation) as well
as binary archive (contains freetype2.dll).
Unpack development archive to e.g. c:\librarys\freetype2 folder.

Note: makefile.mingw assumes freetype2 library is located relative to 
      your gtk (see below) location :
      my_gtk_directory/../freetype2
   

Libsigc source package available from http://sourceforge.net/projects/libsigc .
Unarchive libsigc sources to eg. c:\librarys\libsigc++ folder.

If You have correctly installed all MinGW tools start MSYS shell, change
directory to Your libsigc location e.g.:

  cd librarys/libsigc++

and run 'configure' script

  ./configure

As a result You should have file 'makefile'. Next You can start libsigc compilation. Type:

  make 

Now you should have libsigc library(s) ready for use with k3d compilation.
 

If you have libsigc++ version 1.2.2 or 1.2.3 compilation may be stopped due to 
the error (?) in 'libtool' file - also created by confirure script. Edit 'libtool' file, 
locate line which looks like:
    # The default C compiler.
and change the next line which is:
    CC="gcc"
onto
    CC="g++"
Then save 'libtool' file and run again make...

 
Once again compilation can be breaked when import library for tests is created.

To correct that:
from       c:/librarys/libsigc++/sigc++/.libs 
copy file  libsigc-1.2-5.dll-def 
to         c:/librarys/libsigc++/tests/.libs 
and run make third time... That should finish libsigc++ compilation...


You can also run:
    make check
to test the result.

As the final step original libsigc++ docs suggests to run:
    make install

Which just copy headers and librarys to  c:/msys/1.0/local/ directory
which seems to be replacement to Unix /usr/local/ .

Current makefile.mingw assumes that libsigc headers and library files are
placed relative to gtk (see below) location.
   my_gtk_directory/../libsigc++


NOTE: in makefile.mingw  var "USE_STATIC_LINK_SIGC" enables linking sdptypes.so 
      with libsigc++ *.lo object files instead of libsigc*.a import lib file. 
      In that case libsigc++1.2-5.dll will be not necessary at runtime. 
      Use it in case of k3d's binaries runtime troubles.




You'll have to install python and ruby packages to compile k3d's python and ruby plugins.


Python for win32 platform is available at http://www.python.org/ as self exctracting
installer. Usually python will be installed in c:/python23 directory and 
python23.dll file will be placed in your system directory.

NOTE: You will need to make a copy of python23.dll file from your system directory 
      into place where your python for win32 keeps library files - c:/python23/libs . 
      MinGW linker will use python23.dll as import library instead of regular import 
      library file libpython23.a which is missed in python installer.
      More info about using *.dll for linking in absence of import lib *.a file
      can be found in MinGW's 'ld' linker documentation.



Ruby scripting language is available at http://www.ruby-lang.org/ . You will need
a source package. Unpack ruby archive into e.g. c:/src/ruby-1.6.8 directory.
To compile ruby start MSYS shell, change directory e.g.:
   cd src/ruby-1.6.8
and run 'configure script:
   ./configure

'Configure' script should create 'makefile'. Now type:
   make
to start 'ruby' sources compilation. 
As the result 'rubys.a' library file should be created - that one will be used
by linker during building k3d's 'rubylib.so' plugin file.

NOTE: on ruby download pages you can find precompiled packages for few 
      platforms and compilers. Also for MinGW. It contains 'mingw*.dll' dynamic
      library file and 'mingw*.a' import library. They can be used to create 
      k3d's 'rubylib.so' module dynamicaly linked with 'mingw*.dll' but it 
      can work incorrect. Instead use static linking  with 'rubys.a' created from 
      sources.



Finaly to enable python and/or ruby k3d's plugin(s) compilaton add the following
definitions as system's variables e.g.:

   set WITH_PYTHON=1
   set PYTHON_ROOT=./../../python23
   set WITH_RUBY=1
   set RUBY_ROOT=./../ruby-1.6.8  

or set/enable them in 'makefile.mingw'.

PYTHON_ROOT and RUBY_ROOT are root pathes for python and ruby directorys.
They can be an absolute pathes e.g. :
  c:/python23 
or 
  /python23
or
  /c/python23
or relative to k3d's root sources (and 'makefile.mingw') e.g. :
   ./../../python23
if k3d sources are placed in c:/src/k3d .

NOTE: Relative pathes are usually better recognized by MSYS shell and MSYS tools.




GTK+/GLIB available from http://www.gimp.org/~tml/gimp/win32/downloads.html . These
are the developer files for the GTK+ user interface library and support libraries.
You will need the following files:

	glib-dev-********.zip
	libiconv-dev=********.zip
	gtk+-dev-********.zip
	libintl-********.zip

Note: Source archives may be useful too - e.g. you can rebuild GTK/GLIB yourself.
      Web site proposes the libraries for GTK+ 1.3 and 2.x  - to build k3d 
      use gtk version 1.3.
      Runtime packages - contains DLLs - will be necessary to run k3d binaries.

Unarchive these to a suitable directory, I suggest c:\Libraries\mygtk. This will 
create a new subdirectory named mygtk. You will need to setup an environment variable 
to point to this location, it is used in the makefile to locate the appropriate headers 
and libraries.
This will need to be done either in the System settings tool in the control panel
(NT/2000) or in the autoexec.bat file (95/98/ME), it is called GTK_ROOT, i.e.

	set GTK_ROOT=C:/libraries/mygtk

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

3. Building

Using the Msys.bat file, start the MSYS shell. CD into the location 
of the K3D source in the projects subdirectory, and type

	make -f Makefile.mingw

Note: You can copy or rename 'makefile.mingw' to 'makefile' and then just type:

        make 

Don't worry about errors when running this command at first time: there aren't
dependencies .d files and 'make' prints massive amounts of errors which can be
ignored. Dependencies are calculated at next step (it takes some time).
When all .d files are calculated, compilation begins.

After some time you should have a complete build of K3D.

Note: you can start make process directly from ordinary DOS window, but it's better to
run an "sh" shell first. You can then redirect errors and normal terminal messages to
separate files.

4. Running

First you must make sure that the dll's for GTK+ etc are available on the path you will
either need to upate your PATH to point to the installation locations, or copy them to
somewhere on the current path. The dll's you will need are

	libglib-***.dll
	libgmodule-***.dll
	libgtk+***.dll
	libgdk-***.dll
	libintl-***.dll
	iconv***.dll

Also libsigc++1.2-5.dll - if k3d is build without "USE_STATIC_LINK_SIGC" - and 
freetype2.dll should be placed somewhere in your PATH - that may be the same 
location as gtk dlls.
 
If you have build k3d with python plugin be shure You have python23.dll in PATH.
Python's installer places that file into system's directory.



WIN32 CYGWIN/XFREE86 BUILD:
===========================

1. Tools

You will need to obtain recent versions of Cygwin and Cygwin / XFree86 from
http://sources.redhat.com/cygwin.  Note that autoconf, automake, and libtool, which are
required to build K-3D only recently became part of the mainstream Cygwin installation.
Cygwin has a nice graphical installation tool, and Cygwin / XFree86 has excellent
step-by-step instructions for installation.  Make sure you have the development files
for XFree86, and test to see that you can start the X server, open an xterm, etc. before
proceeding.

2. Additional Requirements

You will need to download GLIB and GTK+ (the native X versions) from the GTK+ ftp
server, ftp://ftp.gtk.org/pub/gtk/v1.2/ .  Get the latest versions of GLIB and GTK+,
which were 1.2.10 as of this writing.  Extract the archives, and do

	$ ./configure
	$ make
	$ make install

for each.

3. Building / Running

From this point, you have a native Posix & X environment, and can follow the Posix
instructions, above, with ONE IMPORTANT EXCEPTION ... because Win32 does not have
shared library support (DLLs have some important limitations, and thus don't
qualify in this respect), you MUST configure the build to use statically-linked
plugin libraries.  A recommended configuration for Cygwin would be:

	$ ./configure --without-plib --with-static-plugins --disable-shared

You will find that linking with this configuration under Win32 is incredibly
resource-intensive.  Be prepared for the linker to take more than 150Mb of RAM
and 10-15 minutes to link the final executable.  Because of this, it is also
highly-recommended that you disable debugging support when you compile:

	$ make CXXFLAGS=-Wall


GET K-3D SOURCE FILES DIRECTLY FROM CVS
=======================================

SourceForge instructions are here:
 http://sourceforge.net/cvs/?group_id=11113

Here's the "idiot's guide":

$ cvs -d:pserver:anonymous@cvs.k3d.sourceforge.net:/cvsroot/k3d login
$ cvs -z3 -d:pserver:anonymous@cvs.k3d.sourceforge.net:/cvsroot/k3d co k3d

$ cd k3d
$ cvs -z3 update -d -P

the 3rd & 4th lines, though optional, remove empty directories (i.e. old source
trees not used anymore).

From this point forward, you can update your CVS tree periodically to see what's
happening, with the following:

$ cd k3d
$ cvs -q update -d -P

... "-q" option means "work quietly", which makes it easier to see exactly what's
changed since your last update.  The "-d" option forces the client to retrieve any
newly-added directories in the source tree.  The "-P" option works as above,
removing any empty directories from the source tree.


ADDITIONAL HELP
===============

For an up-to-date set of instructions on how to install K-3D, see:

	http://k3d.sourceforge.net/new/html.php?doc=userreference/book1.html&index=0

All other questions, comments, or concerns should be addressed to the K-3D maintainers:

	http://k3d.sourceforge.net

Thank you,
The K-3D Team






Basic Installation
==================

   These are generic installation instructions.

   The `configure' shell script attempts to guess correct values for
various system-dependent variables used during compilation.  It uses
those values to create a `Makefile' in each directory of the package.
It may also create one or more `.h' files containing system-dependent
definitions.  Finally, it creates a shell script `config.status' that
you can run in the future to recreate the current configuration, a file
`config.cache' that saves the results of its tests to speed up
reconfiguring, and a file `config.log' containing compiler output
(useful mainly for debugging `configure').

   If you need to do unusual things to compile the package, please try
to figure out how `configure' could check whether to do them, and mail
diffs or instructions to the address given in the `README' so they can
be considered for the next release.  If at some point `config.cache'
contains results you don't want to keep, you may remove or edit it.

   The file `configure.in' is used to create `configure' by a program
called `autoconf'.  You only need `configure.in' if you want to change
it or regenerate `configure' using a newer version of `autoconf'.

The simplest way to compile this package is:

  1. `cd' to the directory containing the package's source code and type
     `./configure' to configure the package for your system.  If you're
     using `csh' on an old version of System V, you might need to type
     `sh ./configure' instead to prevent `csh' from trying to execute
     `configure' itself.

     Running `configure' takes awhile.  While running, it prints some
     messages telling which features it is checking for.

  2. Type `make' to compile the package.

  3. Optionally, type `make check' to run any self-tests that come with
     the package.

  4. Type `make install' to install the programs and any data files and
     documentation.

  5. You can remove the program binaries and object files from the
     source code directory by typing `make clean'.  To also remove the
     files that `configure' created (so you can compile the package for
     a different kind of computer), type `make distclean'.  There is
     also a `make maintainer-clean' target, but that is intended mainly
     for the package's developers.  If you use it, you may have to get
     all sorts of other programs in order to regenerate files that came
     with the distribution.

Compilers and Options
=====================

   Some systems require unusual options for compilation or linking that
the `configure' script does not know about.  You can give `configure'
initial values for variables by setting them in the environment.  Using
a Bourne-compatible shell, you can do that on the command line like
this:
     CC=c89 CFLAGS=-O2 LIBS=-lposix ./configure

Or on systems that have the `env' program, you can do it like this:
     env CPPFLAGS=-I/usr/local/include LDFLAGS=-s ./configure

Compiling For Multiple Architectures
====================================

   You can compile the package for more than one kind of computer at the
same time, by placing the object files for each architecture in their
own directory.  To do this, you must use a version of `make' that
supports the `VPATH' variable, such as GNU `make'.  `cd' to the
directory where you want the object files and executables to go and run
the `configure' script.  `configure' automatically checks for the
source code in the directory that `configure' is in and in `..'.

   If you have to use a `make' that does not supports the `VPATH'
variable, you have to compile the package for one architecture at a time
in the source code directory.  After you have installed the package for
one architecture, use `make distclean' before reconfiguring for another
architecture.

Installation Names
==================

   By default, `make install' will install the package's files in
`/usr/local/bin', `/usr/local/man', etc.  You can specify an
installation prefix other than `/usr/local' by giving `configure' the
option `--prefix=PATH'.

   You can specify separate installation prefixes for
architecture-specific files and architecture-independent files.  If you
give `configure' the option `--exec-prefix=PATH', the package will use
PATH as the prefix for installing programs and libraries.
Documentation and other data files will still use the regular prefix.

   In addition, if you use an unusual directory layout you can give
options like `--bindir=PATH' to specify different values for particular
kinds of files.  Run `configure --help' for a list of the directories
you can set and what kinds of files go in them.

   If the package supports it, you can cause programs to be installed
with an extra prefix or suffix on their names by giving `configure' the
option `--program-prefix=PREFIX' or `--program-suffix=SUFFIX'.

Optional Features
=================

   Some packages pay attention to `--enable-FEATURE' options to
`configure', where FEATURE indicates an optional part of the package.
They may also pay attention to `--with-PACKAGE' options, where PACKAGE
is something like `gnu-as' or `x' (for the X Window System).  The
`README' should mention any `--enable-' and `--with-' options that the
package recognizes.

   For packages that use the X Window System, `configure' can usually
find the X include and library files automatically, but if it doesn't,
you can use the `configure' options `--x-includes=DIR' and
`--x-libraries=DIR' to specify their locations.

Specifying the System Type
==========================

   There may be some features `configure' can not figure out
automatically, but needs to determine by the type of host the package
will run on.  Usually `configure' can figure that out, but if it prints
a message saying it can not guess the host type, give it the
`--host=TYPE' option.  TYPE can either be a short name for the system
type, such as `sun4', or a canonical name with three fields:
     CPU-COMPANY-SYSTEM

See the file `config.sub' for the possible values of each field.  If
`config.sub' isn't included in this package, then this package doesn't
need to know the host type.

   If you are building compiler tools for cross-compiling, you can also
use the `--target=TYPE' option to select the type of system they will
produce code for and the `--build=TYPE' option to select the type of
system on which you are compiling the package.

Sharing Defaults
================

   If you want to set default values for `configure' scripts to share,
you can create a site shell script called `config.site' that gives
default values for variables like `CC', `cache_file', and `prefix'.
`configure' looks for `PREFIX/share/config.site' if it exists, then
`PREFIX/etc/config.site' if it exists.  Or, you can set the
`CONFIG_SITE' environment variable to the location of the site script.
A warning: not all `configure' scripts look for a site script.

Operation Controls
==================

   `configure' recognizes the following options to control how it
operates.

`--cache-file=FILE'
     Use and save the results of the tests in FILE instead of
     `./config.cache'.  Set FILE to `/dev/null' to disable caching, for
     debugging `configure'.

`--help'
     Print a summary of the options to `configure', and exit.

`--quiet'
`--silent'
`-q'
     Do not print messages saying which checks are being made.  To
     suppress all normal output, redirect it to `/dev/null' (any error
     messages will still be shown).

`--srcdir=DIR'
     Look for the package's source code in directory DIR.  Usually
     `configure' can determine that directory automatically.

`--version'
     Print the version of Autoconf used to generate the `configure'
     script, and exit.

`configure' also accepts some other, not widely useful, options.
