Building

If you have a source distribution -- excellent -- this page will help you compile the tools and test.

The build instructions for Windows and Linux (and other *nix versions) follow this section. For orientation, the various projects and their directories are as follows:

tests. Tthe testbed and demo application. See Demo.

  • Linux: tests/krdemo
  • Windows: tests/release/krdemos.exe

encoder. The Encoder which creates the data files Kyra uses from source graphics. See Tools.

  • Linux: ../encoder/krencoder
  • Winodws: ..\encoder\release\krencoder

engine. Builds the Kyra Engine to a library file, that can be statically or dynamically linked.

Note that no attempt has been made at binary compatibility between versions of Kyra, so I don't recommend dynamic linking unless you can be sure of version of the dynamic library you'll be loading.

The code for a sprite engine is small compared to the assets that it uses. Static linking is easier and more reliable, and should probably be used for a shipping product. Dynamic linking can be convenient during development.

spriteed. The Sprite Editor. See Tools.

  • Linux: ../spriteed/krspriteed
  • Windows: ..\spriteed\release\krspriteed

guitest. Kyra provides some simple, extensible widgets. See Engine.

  • Linux: ../guitest/krguitest
  • Windows: ..\guitest\release\krguitest

Windows

The Windows version .dsw and .dsp files are for building under Microsoft's Visual C++ version 6 or higher.

The Kyra project needs (like any SDL client) the following connections to SDL:

  1. At compile time, the compiler needs to be able to find the SDL headers.
  2. At link time, the linker needs to be able to find your sdl.lib and sdlmain.lib files.
  3. At run time, the executable needs to find your sdl.dll (and for other projects, sdl_image.dll) file.

To accomplish this this is Visual Studio, go to Tools::Options::Directories. Under the "Show Directories For" tab, choose "Include files". In the path list box, add the path to your SDL include files (/SDL/include depending on where you installed it.) The compiler can now locate the SDL headers. Make sure both the SDL and SDL_image headers are at the same location, or add another path for SDL_image.

Switch "Show directories for" to library files, and add a path to where your sdl.lib, sdl_image.lib, and sdlmain.lib files are. The linker will now be able to find the library files.

For run time, sdl.dll and sdl_image.dll will need to be available. Windows will search directories in the followng order for these dll's:

  1. The directory from which the application loaded.
  2. The current directory.
  3. The Windows system directory.
  4. The directories that are listed in the PATH environment variable.

Once you've gone through these steps, they are applied to all your projects and you shouldn't have to go through them again.

Build Process

  1. From the Visual Studio IDE, open 'Kyra.dsw' in the kyra root.
  2. Select Build->Batch Build. Build everything except the 'demos' and 'tutorial1' projects. This builds the libraries and the tools.
  3. Before you can build the demo project, you need to build the .dat file that supplies the resources for the sprite engine. On the command line, switch to the 'tests' directory, and run 'encodeall.bat'. This creates the resources needed by the executable. You will see a bunch of graphics screens be displayed as they are processed. Press the spacebar to clear a screen and move to the next.
  4. Back in the IDE, build the release or debug of the 'demos' project.

Build Options

The Windows project files have KYRA_SUPPORT_OPENGL turned on by default in "ProjectSettings --> C/C++ --> Preprocessor definitions". Remove the #define to disable OpenGL support. Note that with KYRA_SUPPORT_OPENGL turned on, you need to link your executable with the opengl32.lib.

Linux

Linux is an easier build process than Windows, fortunately. First, verify that you have SDL and SDL_image correctly installed. From the command line, 'sdl-config --version' should return version 1.2 or higher.

You have 2 build choices: using the "old skewl" make files, or using the autotools system. The autotools code is the preferred choice for many. It is also newer, and feedback is appreciated.

Autotools

Note: if upgrading from a previous version installed with 'configure', I suggest switching to your Kyra directory and running make uninstall to clean up your system before starting.

From the Kyra root,

  1. ./configure
  2. make
  3. make install (note that you may neet root privilege to install)

From the tests subdirectory,

  1. ./encodeall
  2. ./configure
  3. make

    kyra-config

    The utility "kyra-config" will return path and version information. Your app builds with a command line something like this:

    g++ yourkyraapp.cpp `kyra-config --cflags` `kyra-config -libs` -o yourkyraapp

    Build Options

    ./configure --with-debug will build a debug version of the kyra library.
    ./configure --with-opengl will turn on OpenGL support.

Traditional make

  1. From Kyra directory, 'make -f MakefileKyra'. This will build all the projects except the test application. 'make depend' is no longer necessary. The dependencies are hard-coded to the make files.
  2. Switch to the 'tests' subdirectory.
  3. './encodeall' This will build the resources for the demo. Screenshots will be displayed of the resource. Press the spacebar to move to the next screen.
  4. From the tests directory again, 'make -f MakefileKyra'. The test application is now ready to run.

Kyra also supports the "make install' target. "make install" will copy:

  • headers to usr/local/include/kyra
  • libkyra.a and libkyra_1_x_y.a to usr/local/lib

Note that Kyra does not have binary compatibilty between versions of its libraries. It is highly recommended that clients of kyra link to the libkyra_1_x_y.a library, or make sure of the Kyra version they link against, in order to guarentee they link and run correctly.

Build Options

The Linux/FreeBSD makefile supports the following environment variables. You can set them with the Bash shell with the export command. For example, MAKE_KYRA=DEBUG.

  • MAKE_KYRA=DEBUG | RELEASE | PROFILE. Build Kyra for release or with debugging information. Building with debugging information can be *very* helpful when developing with Kyra.
  • KYRA_OPENGL=YES. If set to yes, will compile Kyra with OpenGL support. Default is to not include OpenGL support, since some Unix systems seem to have trouble with it. (Once Kyra switches over to autoconf & automake we should be able to detect this more easily.)

Using or Linking Kyra to Your App

Both the Windows and Linux builds provide static link time libraries. This is probably the easiest way to use Kyra. Note that Kyra is not binary compatibile between versions...so be sure that the Kyra library you are using is consistent with the headers you include.

The file "kyra.h" is provided in the "engine" subdirectory. The most common Kyra headers are included by this file, so you can use it as a one stop include.

As of 1.5, if OpenGL support is turned on, the target executable will need to link with OpenGL. For Win32, link with opengl32.lib. For Linux, link with the GL library. By default, OpenGL support is ON in Windows, OFF in Linux.