$Id: FAQ,v 1.1.1.1 2000/04/09 12:17:58 mbn Exp $

            Frequently Asked Questions about the ClanLib Library

This document tries to answer questions a user might have when installing and
using ClanLib.  Please make sure you read this before sending questions or bug
reports to the maintainers.

If you have any questions you think should be answered in this document, please
read the document README to find out where to direct your questions.
If you find any errors or outdated information in this document, please let me
know at sphair-faq@dark.x.dtu.dk.

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

1. Compiling under Linux
  1.1.  When I try to compile ClanLib, I get errors regarding that try, catch
        and throw are reserved C++ keywords.
  1.2.  My C++ compiler wants exceptions to be enabled with -fhandle-exceptions.
  1.3.  I get an "Internal compiler error" message from my C++ compiler. 
  1.4.  It can't find -lGL when trying to build clanGL:
  1.5.  When compiling it complains that it cannot open shared object
        libclanCore:
  1.6.  When I run ./configure, I get errors about missing files:
  1.7.  I'm using PGCC, and I get error while compiling a file called virtch.c.
  1.8.  I'm using Mandrake Linux, and I get an error while compiling a file
        called virtch.c?
  1.9.  I'm using SuSE and am getting warnings about multiple common of:
  1.10. I'm using SuSE and cannot locate libz.so. 
  1.11. My compiler dies with a 'MAP_FAILED undeclared' message.

2. Installing under Linux
  2.1.  When trying to install the ClanLib rpms I get failed dependencies:

3. Running under Linux
  3.1.  I've installed Hermes, but when I try and run any ClanLib appliction, I
        get errors about cannot open shared object file libHermes:

4. Compiling under Windows
  4.1.  I try to compile an app using ClanLib under Visual C++ and it gets
        unresolved external symbol _main:
  4.2.  I try to compile an app using ClanLib under Visual C++ and it gets
        unresolved external symbol _WinMain:
  4.3.  How can I compile ClanLib under Win32 using Borland C++ compiler?
  4.4.  Can I use the windows binaries with a Borland compiler ?
  4.5.  What is the configure app ?

5. Installing under BeOS
  5.1.  I'm using BeOS, where do I have to put the ClanLib libraries in order to 
        compile anything using them - configure won't recognize their existence?

6. Programming issues
  6.1.  I want to create a font using resource, but I get a problem when the
        font contains the letters ,;#{}()="
  6.2.  How do I get access to the frame buffer?
  6.3.  How can I create a full screen game with ClanLib under Linux?
  6.4.  Are there plans to add support for Alpha blending?
  6.5.  What happened to the Datafilecompiler since 0.3.0 ?
  6.6.  How do I compile the datafiles ?
  6.7.  When I try to run my ClanLib program, it tells me there is no global
        CL_ClanApplication instance:
  6.8.  When will clanMPEG include sound support ?
  6.9.  I don't think the datafile compiler should be in our app!

7. CVS
  7.1.  Where can I find version 0.4.x in CVS?
  7.2.  I run WinCVS, and it exits with code 0:

8. Misc
  8.1.  Where ClanLib name came from? What's the clan for? 


--------------------------------------------------------------------------------
1. Compiling under Linux
--------------------------------------------------------------------------------
1.1.  When I try to compile ClanLib, I get errors regarding that try, catch and 
      throw are reserved C++ keywords.

1.2.  My C++ compiler wants exceptions to be enabled with -fhandle-exceptions. 

1.3.  I get an "Internal compiler error" message from my C++ compiler. 

Answer:
      Try upgrading your compiler to a newer version.

--------------------------------------------------------------------------------
1.4.  It can't find -lGL when trying to build clanGL:

      Building glx target/usr/bin/ld: 
      cannot find -lGL
      collect2: ld returned 1 exit status
      make: *** [Libs/libclan-display-glx.so.0.4.0] Error 1 

      So naturally I verified if I had a libGL and I have one in /usr/X11R6/lib.
   
      What's wrong here?

Answer:
      TODO: someone fill this in

--------------------------------------------------------------------------------
1.5.  When compiling it complains that it cannot open shared object libclanCore:

      error in loading shared libraries: libclanCore.so.0: cannot open shared
      object file: No such file or directory

Answer:
      Chances are you installed the clanlib libraries into /usr/local/lib, but
      /usr/local/lib isn't present in the /etc/ld.so.conf. You can choose to
      install in a directory that IS present in /etc/ld.so.conf or choose to add
      /usr/local/lib to ld.so.conf. Remember to run ldconfig as root afterwards.

--------------------------------------------------------------------------------
1.6.  When I run ./configure, I get errors about missing files:

      In file included from Sources/Lua/clanLua.cpp:15:
      Sources/Lue/tolua/tolua.h:28: lua.h: No such file or directory

      or this...
	
      In file included from Sources/MikMod/streamed_mikmod_sample.cpp:19:
      Sources/API/MikMod/streamed_mikmod_sample.h:28: mikmod.h: No such file or
      directory

      or any similar configure errors.

Answer:
      These are just warnings about missing files for some of the external
      ClanLib components. They can safely be ignored unless you are going to
      compile the extra libraries. If so, you need to install the correct
      packages (Lua, MikMod, PNG, ImageMagick etc).

--------------------------------------------------------------------------------
1.7.  I'm using PGCC, and I get error while compiling a file called virtch.c.

Answer:
      Open makefile.conf, search for -O3 and replace it with -O6.

--------------------------------------------------------------------------------
1.8.  I'm using Mandrake Linux, and I get an error while compiling a file called
      virtch.c?

Answer:
      Until Mandrake 7, PGCC is the default compiler; check out question 1.7,
      or upgrade to Mandrake 7.

--------------------------------------------------------------------------------
1.9.  I'm using SuSE and am getting warnings about multiple common of:

      obj/Input.o: warning: multiple common of 'CL_InputAxis type_info node'
      /usr/local/lib/libclan.so: warning: previous common is here

Answer:
      To get rid of those annoying "multiple common..." warnings edit 
      /usr/lib/gcc-lib/i486-linux/egcs-???/specs. 

        *lib
        -warn-common%{share....

      should be:

        *lib
        %{share...

--------------------------------------------------------------------------------
1.10.  I'm using SuSE and cannot locate libz.so. 

Answer: 
      Zlib is called libgz.so on SuSE systems prior to 6.2. 
      To fix, try this as root:

        ln -s /usr/lib/libgz.so /usr/lib/libz.so && ldconfig

      It creates a symlink and updates the library cache.

--------------------------------------------------------------------------------
1.11. My compiler dies with a 'MAP_FAILED undeclared' message.

Answer:
      We've had reports from people using the Slackware Linux distribution that
      the compile fails because MAP_FAILED is undefined. This is supposed to be
      in sys/mman.h as a return value of mmap(), but apparently isn't on some
      systems. We don't know if this is a Slackware problem or a libc5/kernel
      issue, but feel free to enlighten us.

      Until then, we recommend pasting the following code into your
      /usr/include/sys/mman.h, or in some other headerfile if you prefer not to
      muck with your system header files (or don't have permissions?)

        #ifndef MAP_FAILED
        #define MAP_FAILED ((__ptr_t) -1)
        #endif


--------------------------------------------------------------------------------
2. Installing under Linux
--------------------------------------------------------------------------------
2.1.  When trying to install the ClanLib rpms I get failed dependencies:

      failed dependencies:
	  libstdc++-libc6.1-1.so.2 is needed by ClanLib-...
	  libm.so.6(GLIBC_2.1) is needed by ClanLib-...
	  libc.so.6(GLIBC_2.0) is needed by ClanLib-...

Answer:
      You don't have a new enough version of glibc. This usually happens when
      using the RPM's on a RedHat 5.x system, while the rpms were compiled on RH
      6.0.

      You need to install these (or newer) RPM's: (get them from RedHat's site)

        rpm -i glib-1.2.1-2.i386.rpm
        rpm -i glibc-2.1.1-6.i386.rpm --upgrade
        rpm -i libstdc++-2.9.0-12.i386.rpm

      This will enable you to use most RedHat 6.0 RPMs on the net, not just
      ClanLib's.


--------------------------------------------------------------------------------
3. Running under Linux
--------------------------------------------------------------------------------
3.1.  I've installed Hermes, but when I try and run any ClanLib appliction, I
      get errors about cannot open shared object file libHermes:
   
      error in loading shared libraries: libHermes.so.1: cannot open shared
      object file: No such file or directory

Answer:
      Upgrade to latest Hermes (as FAQ was written this was version 1.3.0).


--------------------------------------------------------------------------------
4. Compiling under Windows
--------------------------------------------------------------------------------
4.1.  I try to compile an app using ClanLib under Visual C++ and it gets
      unresolved external symbol _main:

      Linking...
      LIBCD.lib(crt0.obj) : error LNK2001: unresolved external symbol _main

Answer:
      You have to create a Win32 Application project and not a Win32 Console
      Application.
   
--------------------------------------------------------------------------------
4.2.  I try to compile an app using ClanLib under Visual C++ and it gets
      unresolved external symbol _WinMain:

      Linking...
      LIBCD.lib(crt0.obj) : error LNK2001: unresolved external symbol
      _WinMain@16

Answer:

TODO: Link to installation guide

--------------------------------------------------------------------------------
4.3.  How can I compile ClanLib under Win32 using Borland C++ compiler?

4.4.  Can I use the windows binaries with a Borland compiler ?

Answer:
      ClanLib does not currently support anything but Microsoft Visual C++
      under Windows. But it should be possible to use ClanLib with other
      compilers. If people want to use Borland C++ together with ClanLib, notice
      that there are three things you need to be aware of:

      1. You cannot use the win32 binaries. Because there is no standard on the
         symbol names used, it will be only Visual C++ 6.0 that those are
         gauranteed to work with.

      2. The configure application uses MFC. AFAIK it is not part of Borland
         C++, and I don't know if it is possible to compile it for Borland users
         without trouble.

      3. You will have to make your own makefile.


      Unfortantly, it is impossible for us to support a compiler we don't have.

--------------------------------------------------------------------------------
4.5.  What is the configure app ?

Answer:
      In the source package, there is a workspace called Configure.dsw. It
      produces the real workspace and project files based on some questions
      asked in a MFC Wizard.

--------------------------------------------------------------------------------
5. Installing under BeOS
--------------------------------------------------------------------------------
5.1.  I'm using BeOS, where do I have to put the ClanLib libraries in order to 
      compile anything using them - configure won't recognize their existence?

Answer:
      Put them into /boot/beos/system/lib - It is not a good place for user 
      installed libs but they are recognized there.

TODO: Status on BeOS


--------------------------------------------------------------------------------
6. Programming issues
--------------------------------------------------------------------------------
6.1.  I want to create a font using resource, but I get a problem when the font
      contains the letters ,;#{}()="

Answer:
      Enclose the letters in ", and use "" to specify ".
      Example: ... (type=font, ..., letters="abcdef0123456,;""#{}()=");
   
TODO: Verify this still work.

--------------------------------------------------------------------------------
6.2.  How do I get access to the frame buffer?

Answer:
      Most likely you only want access to surface data and this can be
      accomplished by using surface->get_provider()->get_data() after locking
      the provider. Don't forget to surface->reload() if you changed the data.
   
--------------------------------------------------------------------------------
6.3.  How can I create a full screen game with ClanLib under Linux?

Answer:
      Use the GGI target of ClanLib and set the following environment variable
      before you start the game:

        $ export GGI_DISPLAY=dga

      Note that you will have to run the game as root or setuid root for this to
      work.

--------------------------------------------------------------------------------
6.4.  Are there plans to add support for Alpha blending?

Answer:
       We do support alpha blending. Just load an image with alpha values, and
       it will alpha blend when put_screen'ed.

--------------------------------------------------------------------------------
6.5.  What happened to the Datafilecompiler since 0.3.0 ?
   
6.6.  How do I compile the datafiles ?

Answer:
      The datafile compiler is now part of your executable. So if your app
      executable is called FooBar, your produce it like this:

          ./FooBar -datafile FooBar.scr FooBar.dat

      and with Windows:

          FooBar.exe -datafile FooBar.scr FooBar.dat

      If you want the makefile to build it, do something like this:

          FooBar.dat: FooBar FooBar.scr
            ./FooBar -datafile FooBar.scr FooBar.dat

          FooBar: $(OBJF)
            g++ -o FooBar $(OBJF) -lclanCore

          all: FooBar FooBar.dat

      If you're using Windows, you enter the project settings menu, and add a
      custom build to FooBar (top tree node), and write the following:

          $(INPUTPATH) -datafile FooBar.scr FooBar.dat

      That should make it build the datafile.

--------------------------------------------------------------------------------
6.7.  When I try to run my ClanLib program, it tells me there is no global
      CL_ClanApplication instance:

	ClanLib: No global CL_ClanApplication instance!!!

Answer:
      The CL_ClanApplication class must be inherited by all ClanLib
      applications. In your application you must create a class inheriting
      CL_ClanApplication, make a global instance of it, and fill in the main(),
      get_title(), init_modules() and deinit_modules() functions. 

--------------------------------------------------------------------------------
6.8.  When will clanMPEG include sound support ?

Answer:
	TODO

--------------------------------------------------------------------------------
6.9.  I don't think the datafile compiler should be in our app!

Answer:
      There is a technical reason that the compiler was made a part of the app
      (custom resources). Originally it was the intention that the compiler can
      be explict disabled if people do not want users to invoke the compiler,
      but that has so far not been implemented.


--------------------------------------------------------------------------------
7. CVS
--------------------------------------------------------------------------------
7.1.  Where can I find version 0.4.x in CVS?

Answer:
      Its currently called ClanLib-0.3 in CVS.

--------------------------------------------------------------------------------
7.2.  I run WinCVS, and it exits with code 0:

      *****CVS exited normally with code 0******

      What do I do wrong ?

Answer:
      Nothing, this simply means everything went OK.


--------------------------------------------------------------------------------
8. Misc
--------------------------------------------------------------------------------
8.1.   Where ClanLib name came from? What's the clan for? 

Answer:
       The Clan prefix originates from the term "The Norddahl Clan". On the old
       fido net, we were called this because we always shared the same opinions.

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


TODO:
- Add 8 bit display
- Fonts (how to create)
- Other TODOs around the document
