Free Electron
Developer Setup Guide

OUTDATED.

This page still needs an overhaul.

This guide describes the process of creating a development environment for the Free Electron codebase, from scratch. Note that this is a *developer* setup guide, not a *user* setup guide. There are sections for each platform supported by Free Electron. The following assumptions are made regarding the state of the target system:


Please refer to the section associated with your system:

Common

  1. get svn access:
    • email AJ and get an imonk account (you'll use this for svn access, and for web access)


  2. The following environment variables are required:

    Variable Value Example Description
    FE_ROOT <path to local FE svn repo> D:\projects\fe\subversion A convenience variable leveraged by several others
    CODEGEN buildtype [debug,optimize,profile] debug Used by Forge to dictate the nature of the build.
    FE_LIB <path to desired lib directory for generated binaries> D:\projects\fe Instructs Forge to create and use a lib directory at the specified location for all generated libs. If not specified, Forge will use $FE_ROOT instead.


    The following environment variables are recommended but aren't technically necessary:

    Variable Value Example Description
    PRETTY anything 1 Used to colorize Forge's shell output. The value of this var doesn't matter, as Forge only checks whether or not it exists.
    CCACHE_DIR <path to local ccache temp> /usr/tmp/ccache Instructs Forge to leverage ccache, and specifies the ccache temp directory.
    FE_E_ASSERT non-zero value 1 Causes an assert to occur whenever an exception would have been thrown.
    FE_OBJ <path to desired obj directory for generated object files> D:\projects\fe Instructs Forge to create and use a obj directory at the specified location for all generated object files. If not specified, Forge will use $FE_LIB instead.


    Linux

    pending...

    Win32

    1. Do everything stated in the Common section above.

    2. The following environment variables are required:

      Variable Value Example Description
      FE_PATH <paths to local FE binaries> %FE_ROOT%\bin;%FE_LIB%\lib\x86_win32_%CODEGEN%;
      %FE_LIB%\lib\x86_win32_%CODEGEN%\fe;      		 A convenience variable used to make the generated binaries easy to execute.
      HASH_MAP_OVERRIDE non zero value 1 Causes std::map to appear as ext::hash_map in the code.


    3. Install MSVC++:
      • NOTE: only Microsoft Visual Studio .NET (v7.1) is officially supported. MSVC++ v6.0 is not sufficiently C++ compliant.
      • Ensure that the MS Visual C++ tools (linker and compiler) are able to run from a shell (command line). In order for them to do so, certain environment variables must be set. The MSVC++ installer normally asks whether or not these variables should be set. If you didn't let the MSVC++ installer set the variables, or you're not sure, then you need to run the VCVARS32.BAT file that sets the variables. This bat file should exist in your MSVC++ folder (typically, C:\Program Files\Microsoft Visual Studio\VC98\Bin). It's advised to run the version of this file that exists on your system, as it will be configured correctly for the directories on your system. Attempts to substitute for it, or use a custom env are beyond the scope of this guide.


    4. Install Python
      • If you already have Python on your system, please verify that it is v2.2.3 (you can do this by just running IDLE, the python console, which will display the version at the top). If it is not, we make no guarantees regarding FE functionality. A non-debug build of FE might work on a different Python version, but you're asking for trouble.
      • go to the Python downloads page
      • download the win32 install. Note that we are currently using v2.2.3. Even if newer versions of Python are available, you should use v2.2.3 until this document indicates otherwise. The reason that the version is important is because Python maintains its own shell variables, and they need to sync up with the python debug binaries that we provide which had to be built with a particular version of the python source.
      • install it.
      • set the following environment variables:
        Variable Value Example Description
        PYTHON_ROOT <root directory of your python installation> "C:\Program Files\Python22" Used by scripts to locate python binaries, modules, etc..
        PYTHON_VERSION major.minor python version 2.2 The major.minor version number of the pyton installation. NOTE - it is very important that you DO NOT include the third version number (use 2.2 NOT 2.2.3)
        PYTHONPATH <directory of your FE binaries> %FE_PATH% An additional set of directories that the Python interpreter considers as part of its $PATH. NOTE - if this variable already exists after you install Python, then just append the FE part to it.


      • Python is FE's primary supported scripting language. Test scripts, demos, tools, etc. are all actively being developed with Python.
      • If you would like color output from the build system, install the WConio package (http://newcenturycomputers.net/projects/wconio.html)


    5. Install Boost
      • If you already have Boost installed on your system you can skip this section.
      • go to the Boost files page
      • download a boost package file (zip/bz2/gz). We're currently using v1.31.0.
      • unzip the boost package someplace (semi-permanent). Note that unzipping will create a boost_1_31_0 directory. If that annoys you as much as it does me, just rename it to 'Boost'. That way, if you were to upgrade boost, you wouldn't have to track down references to the version-ized directory name. Whatever you call it, all subsequent directory references as relative to this root directory.
      • run boost\tools\build\jam_src\build.bat (this builds boost.jam, which is boost's build tool)
      • NOTE: if that completes successfully, not only will you have built boost.jam, but you'll also have verified that the MSVC++ environment variables are established correctly to allow command line compiling and linking.
      • That created a directory called bin.ntx86, which contains the boost.jam executables. Add the path for these executables to your $PATH environment variable (or, if you don't care, you can just copy the executables to somewhere that is already in the $PATH, such as your $WINDIR\system32 directory).
      • ensure that the appropriate Python environment variables have been set (see the Python section above). Boost relies on them to build the Boost.Python library.
      • edit boost\boost\config\user.hpp such that it contains:

        #define BOOST_THREAD_NO_LIB

        There's a section for this kind of directive at the bottom of user.hpp, so just read the comment and add the line.
      • Now, you're ready to build the Boost libs. Open a console in the Boost root directory (where you unzipped the boost files (e.g. C:\projects\boost_1_31_0), and run the following command:
        bjam "-sTOOLS=vc7.1" --prefix=D:\projects\boost_1_31_0 install

        This takes quite awhile, so go get a drink or something. Upon completion, you should see something like, "...updated 3121 targets..." The '--prefix' argument allows you to specify where boost installs itself. Thus, if like me you didn't want the 'boost_1_31_0' directory, change the argument to reflect whatever you named the root boost directory.
      • set the following environment variables:
        Variable Value Example Description
        BOOST_VERSION specially formatted boost version number 1_31 Used by Forge to correctly identify boost binaries. NOTE -- this variable MUST NOT exist *BEFORE* you build boost, only afterwards. If you're rebuilding boost, delete this variable first, and then replace it after the boost build finishes. If you don't, boost installs itself using '1__1' which is bad.
        BOOST_INCLUDE <directory of the boost header files> D:\projects\Boost\include\boost-%BOOST_VERSION% Used by Forge to allow the correct inclusion of boost header files.
        BOOST_LIB <root directory of the generated boost binaries> D:\projects\Boost\lib Used by Forge to allow correct linking to the boost binaries.
        BOOST_STRUCTURE installtype [install,bin-stage] install Used by Forge to allow correct usage of boost files. Not sure exactly what this does...


      • FE uses Boost for uh, horribly obfuscating our own build process, for the purpose of alienating anyone who would otherwise be inclined to help on the project. If you're curious about Boost, read the boost documentation. We'll eventually provide a specific list of the boost libraries used by FE.


    6. Install DevIL
      • FE requires DevIL v1.6.5 or greater. Even if you already have DevIL on your system, please verify the version, and that the appropriate environment variables are set.
      • go to the DevIL downloads page
      • download the windows SDK (currently v1.6.5)
      • unzip it someplace (semi-permanent). Note, it will create its own 'DevIL' directory when unzipped.
      • set the following environment variable:
        Variable Value Example Description
        DEVIL <directory of the boost header files> D:\projects\DevIL Convenience variable leveraged when appending to some other env vars.


      • FE uses DevIL for some image manipulation. If you're curious about DevIL, read the documentation.


    7. Install SDL (Simple DirectMedia Layer)
      • FE requires SDL v1.2.7 or greater. Even if you already have SDL on your system, please verify the version, and that the appropriate environment variables are set.
      • go to the SDL downloads page
      • download the win32 development libraries (currently v1.2.7)
      • unzip the SDL package someplace (semi-permanent). Note that unzipping will create a SDL-1.2.7 directory. If that annoys you as much as it does me, just rename it to 'SDL'. That way, if you were to upgrade SDL, you wouldn't have to track down references to the version-ized directory name. Whatever you call it, all subsequent directory references as relative to this root directory.
      • FE uses SDL for stuff. If you're curious about SDL, read the introduction.


    8. Install Subversion
      • If you already have Subversion installed on your system you can skip this section.
      • go to the Subversion downloads page
      • follow the instructions for installing Subversion via a source tarball, or get one of the pre-packaged setup files for win32. We're currently using v1.0.5.
      • FE uses Subversion for revision control. You are highly encouraged to peruse the Subversion book if you aren't familiar with Subversion.


    9. Get the codebase using Subversion
      • using a console window, change into (or create) the directory that you want to contain your local FE repository. NOTE -- this must be the same directory that you specify as $FE_ROOT
      • execute the following subversion command to retrieve the FE repository:
        svn co https://imonk.com/svn/fe .

        NOTE: the '.' tells svn to use the current directory. If you don't specify a target directory, you'll likely wind up with an extra 'fe/' that you didn't intend to have.
      • you'll get a notice about the imonk SSL certificate. Press 'p' to have subversion accept the certificate permanently.
      • you'll be prompted to enter your imonk password. If you don't have an imonk account, email AJ to get one.
      • once that finishes, you'll possess a local, subversion managed copy of the FE codebase.


    10. Finish setting up the environment variables:
      • Add the following to the INCLUDE variable:
        • %DEVIL%\include
      • Add the following to the LIB variable:
        • %DEVIL%\lib
      • Add the following to the PATH variable:
        • %PYTHON_ROOT%
        • %PYTHONPATH%
        • %BOOST_LIB%
        • %DEVIL%\lib
        • %FE_PATH%


    11. You can now generate any targets:
      • cd $FE_ROOT
      • in a console window, enter: forge.py -d [target] (e.g.: forge.py -d root)
      • If you used 'forge.py -d root' as your first target (and it's recommended that you do), then you'll know whether or not things worked correctly by observing the results of the suite of unit tests (both python scripts and executables) which runs automatically.
      • You can run 'forge.py -h' to see a brief summary of forge.py command line usage.
      • Eventually, one of us will get around to providing a nice home online for Forge, and we would subsequently provide a link to it here.


    12. Build the IDE workspace and project files (if you wish to use the MSVC IDE):
      • NOTE: MSVC project files are currently NOT supported! We will address this issue as soon as we can afford to do so, but it simply is not a high priority at this time. We fully intend to provide complete support for MSVC .NET project files. We will NEVER generate MSVC 6.0 project files (as stated above, MSVC 6.0 is not sufficiently C++ compliant for our purposes).
      • The auto-generated MSVC files should be considered read-only. Changes made to the project settings within the IDE will not be reflected in the official build process. All official build settings must be managed through the associated forge files.


    If you want to do local builds of the documentation:

    1. Install doxygen
      • If you already have Doxygen installed on your system you can skip this section.
      • go to the Doxygen downloads page
      • follow the instructions for installing Doxygen via a source tarball, or get the pre-packaged win32 setup (currently at v1.3.7).
      • doxygen is an automated documentation tool. It uses its own syntax for embedded markups in source code. It's the best thing since sliced bread, and if you write software you should use it.
    2. Install graphviz
      • If you already have Graphviz installed on your system you can skip this section.
      • go to the Graphviz downloads page
      • If you're feeling really adventurous, feel free to attempt an install from source, but there's no reason not to just grab the pre-packaged win32 setup (currently at v1.12).
      • graphviz includes utilities for generating graphs from text descriptions. It is leveraged by Doxygen.
    3. build the doxygen documentation files:
      • cd $FE_ROOT\doc
      • in a console window, enter: doxygen
      • NOTE: if it complains about 'dot', that means that Graphviz isn't properly installed.
      • if you want to create a shortcut to run doxygen, make sure that the working directory is correctly specified, because the doxygen configuration file is inferred.
      • after it's done, you can open up $FE_ROOT\doc\html\index.html
      • It is highly recommended that you peruse the 'Related Pages' section first.
      • The official doxygen-generated Free Electron documentation can always be found online.

    Mac

    These are prliminary notes taken while trying to setup a Mac Mini OSX 10.4

Install Fink.  This is technically not required, but makes life much easier.
http://fink.sourceforge.net

Install subversion (I did via the fink svn-client package...using dselect).

Get FE source:
svn co http://imonk.com/svn/fe/main

Install boost.  There is a fink package in 'unstable', but I did it from source.

Generated by   doxygen 1.8.13