Prerequisites

All platforms

• Chromium's depot tools.
• Java (Release 6 update 13 or later)

Windows

• Windows XP (SP2 or later) or Windows Vista (32 or 64-bit).
• Microsoft Visual Studio 2005 Pro (8.0) or later. Visual Studio Express won't work. Visual Studio 2005/2008 Pro Trial will work.
• set the environment variable "GYP_MSVS_VERSION" to "auto" (optional)

Additional (free) downloads

• If you are using Microsoft Visual Studio 2008, install Service Pack 1.
• Install the Windows 7 SDK.
• You might need to reboot. You can save space by not installing the documentation and code samples.
• Note: Although the SDK download page may give you an impression that it's for Windows 7, it works on Vista, Server 2003, and XP (see the compatibility table).
• Install the DirectX SDK

Mac OS X

• An Intel Mac running Mac OS X 10.5 (“Leopard”) or Mac OS X 10.6 (“Snow Leopard”).
• XCode 3.1.4 (for Leopard) or XCode 3.2.1 (for Snow Leopard). Thankfully, Apple’s build tools are free. All you need is a free Apple Developer Connection account. You can choose to install the iPhone version or not, it doesn't matter.
• To Install Java 6 go to Apple Update, then run the Java Preferences tool found in Applications/Utilities. Move Java 6 to the top of the 2nd list.

Linux

• Python >= 2.4
• gcc/g++ >= 4.2
• g++-multilib >=4.2
• libxt-dev
• libgtk2.0-dev
• a version of OpenGL, at least 2.0, with header files (typically libgl1-mesa-dev, or nvidia-glx-dev). You may also have to install the following packages: libglib2.0-dev libglu1-mesa-dev, libx11-dev. The GL_EXT_framebuffer_object extension support is required.

Checking out the code

The gclient config step only needs to be run once to set up your working directory. It creates a .gclient file in your working directory that identifies the corresponding structure to pull from the repository. The gclient sync step creates several subdirectories. To update your tree in the future, you only need to run gclient sync from anywhere within your working directory.

• Create a directory to hold your source code. We will call it $O3D_ROOT below.

Important: Make sure the full directory path has no spaces.

• In a shell window, execute the following commands:

cd $O3D_ROOT
gclient config http://src.chromium.org/svn/trunk/src/o3d

• To download the initial code, update your checkout as described below.

cd $O3D_ROOT
gclient sync

Building

Just like Chrome, O3D Uses GYP to generate build files for each of the platforms. On Windows, this produces .sln and .vcproj files, on Mac OS X it produces .xcodeproj bundles, and on Linux it produces SConscript files.

Building on any supported platform

If you just want to build regardless of platform you can use gypbuild to do the building for you. From the $O3D_ROOT/o3d folder type ./gypbuild on any platform. For more info about gypbuild try 'gypbuild --help'.

Otherwise for specific platforms see below.

Building on Windows

On Windows, GYP produces the solution files that are to be loaded into Microsoft Visual Studio. The "main" solution file is called "o3d.sln", and will appear in the $O3D_ROOT\o3d\build directory. Load this file into Visual Studio, and build it as you would any other Visual Studio file. The output will appear in the $O3D_ROOT\o3d\build\Debug or $O3D_ROOT\o3d\build\Release directory, depending on the build you do.

Building different renderers

O3D has two different renderers on Windows, a D3D-based renderer, and an OpenGL-based renderer. The D3D renderer is the default, but if you want to build the OpenGL renderer, set the variable "GYP_DEFINES" to "renderer=gl" and run the command gclient runhooks --force to regenerate the solution/vcproj files. Unfortunately switching between renderers requires a rebuild, as they use the same output directories currently.

Building on Mac

On Mac OS X, GYP produces the XCode build files that are to be loaded into XCode. The "main" build file is located in $O3D_ROOT/o3d/build/o3d.xcodeproj. Load this file into XCode, and build it as you would any other XCode file. The output will appear in the $O3D_ROOT/xcodebuild/Debug or $O3D_ROOT/xcodebuild/Release directory, depending on the build you do.

Building on Linux

On Linux, GYP produces SConscript and .scons files. The main SConscript is in $O3D_ROOT/o3d/build/o3d_main.scons. To build this file, use 'hammer' from the software construction toolkit (installed as part of the depot_tools). Change directories into the $O3D_ROOT/o3d/build directory, and type hammer -f o3d_main.scons Note: to build the 64-bit plugin, you need to tell gyp that you are building it, by setting the GYP_DEFINES environment variable to target_arch=x64 before you run gclient sync (or run gclient runhooks --force).

At the moment, Linux requires special instructions to run, see below.

• To clean a specific target from the build directories, use the -c option.
• To silence the build commands, use the -s option.
• To see the full build commands, use the --verbose option.
• By default, the build uses the number of processors plus one as the number of concurrent tasks. To specify a different number, use the -j option, followed by the number of concurrent tasks to perform.
• To execute hammer without changing directory into the location of the .scons file, use the -C option.

hammer -s -j3 -f o3d_main.scons  # build quietly running 3 compiles at a time
hammer --verbose -f o3d_main.scons # display full command lines (useful for debugging compile and links errors)
hammer -C $O3D_ROOT/o3d/build -f o3d_main.scons  # build from where you are

You can also use make instead to build, using similar instructions to Chromium's:

# Update and rebuild makefiles if needed
export GYP_GENERATORS="make"
gclient sync
# Build everything.
make -C $O3D_ROOT O3D_All
# Only build the plugin.
make -C $O3D_ROOT npo3dautoplugin

Note: the output of the make build goes to $O3D_ROOT/out instead of $O3D_ROOT/sconsbuild.

Running/Debugging on Linux

Warning: the Linux version of O3D is still experimental. When trying it is suggested to create a separate profile for Firefox (using firefox -ProfileManager to create it, and firefox -P profile -no-remote to use it).

On Ubuntu and other Debian-derived systems, scons will build a .deb installer package into the artifacts directory (provided dpkg-buildpackage is installed, which you can find in the dpkg-dev package). To install, simply execute sudo gdebi-gtk <file> with the appropriate .deb file (...i386.deb for 32-bit systems, or ...amd64.deb for 64-bit systems).

For non-Debian-derived systems, you currently must install O3D manually. scons builds the plug-in—a shared library named libnpo3dautoplugin.so—into the artifacts directory. This needs to be findable by Firefox, and you have several options for that:

• copy or link it into the ~/.mozilla/plugins/ directory (create it if needed).
• specify the MOZ_PLUGIN_PATH environment variable to be the artifacts directory.

Additionally, that plug-in dynamically links with other shared libraries that Firefox needs to find: libGLEW.so.1.5, libCg.so and libCgGL.so. scons copies them into the artifacts directory. By default, Firefox will find not find them though, which will prevent the O3D plug-in from loading. You have several options again:

• copy/symlink the libraries to /opt/google/o3d/lib. The plugin adds this path to the dynamic loader's search path, so Firefox will find them here. (This is the simplest and cleanest solution.)
• if you have root access and don't have a problem with messing up your system, just copy/symlink those libraries into /usr/lib (or any path visible by the dynamic loader - see /etc/ld.so.conf and ld.so(8)).
• edit the ~/.mozilla/firefox/rc file (create it if you need - it is a shell script that is sourced by the firefox launcher) and add a line that sets LD_LIBRARY_PATH to the path where they can be found (or another safe place where you can copy them).
• specify LD_LIBRARY_PATH (as above) in your environment before launching Firefox.

After you have installed, run Firefox and try our samples (in googleclient/o3d/samples). To debug, firefox -g starts Firefox in gdb.

Running tests

Unit tests

You can run unit tests and other tests using scons.

scons unit_tests  # runs unit tests

Selenium

The Selenium tests form a suite of automated browser integration tests. Several pages are loaded into the browser and actions performed on them to ensure that they function as expected.

The customized selenium script for O3D takes screenshots of the display buffer and uses perceptualdiff to compare them with reference screenshots. Note: Screenshots are only taken and diffed in the test-* builds. (eg. Use MODE=test-dbg-d3d to build the test build of the dbg-d3d)

To run selenium tests, execute:

scons selenium MODE=test-dbg-d3d

(Replace test-dbg-d3d with whichever build you want to test.)

There are several other flags pertaining to selenium that you can use: (eg.)

scons selenium MODE=test-dbg-d3d SELENIUM_VERBOSE=0 SELENIUM_BROWSERS=*firefox    # Test the test-dbg-d3d build on firefox with no verbose output

SELENIUM_VERBOSE = {0, 1} Controls if verbose output is displayed for debugging purposes.

SELENIUM_BROWSERS = Comma-delimited string of browsers to test in selenium.

Currently supported browsers for testing in selenium:

• *firefox
• *googlechrome
• *iexplore

You can choose individual tests like this

scons selenium SELENIUM_TEST_PREFIX=TestSampleRotateModel

Which will effectively test only TestSampleRotateModel. The argument is a prefix so TestSampleW will run any test that starts with TestSampleW.