**G3D 10 Build System Instructions** Overview ========================================================================== G3D builds with a Python script named "`buildg3d`". All of the software required for building and using G3D is available for free on all platforms. Building G3D takes about 20 minutes on a recent desktop computer. The source code repository contains all of the library dependencies. Once you've built G3D, you can update to a newer version in a few minutes as an incremental build. There are two common ways to build G3D: local : You're developing local to the same machine that you're building G3D on. You might want to single-step from your code into G3D source code when debugging. You want fast incremental builds of G3D when you update to get the latest patches. Set your include and data directories to the source tree as described below and use `buildg3d local` to compile the library. distrib : You're building the library for distribution as a binary to other developers, such as students in a university course. Set your include and data directories to the source tree as described below and use `buildg3d distrib` to compile the library. Have your other developers set their environment as described in the Dependent Developers section. If you are experienced with building software libraries and using version control, then you may want to read the Advanced section first, which describes alternative ways of building G3D to reduce your initial download size or deploy precompiled G3D binaries across multiple developers. Run "`buildg3d help`" at the command line for more information about the build sytem. Join our forum https://groups.google.com/forum/#!forum/g3d-users and post to g3d-users@googlegroups.com with questions about the library or build system. Windows Automated ========================================================================== **G3D now provides an installer script for Windows. Download installg3d.cmd and double-click on it.** It will automatically download, install, and configure all of the build tools needed, including Python, SVN, and Visual Studio. The installer can be safely re-run multiple times if it fails or rebooting is required by the tools. _If the installer does not work with your system or you require an offline installation, then follow the instructions below._ Source Code ======================================================================= G3D contains a main repository directory of code and documentation named *G3D10* and a series of auxiliary asset repository directories in the *data10* directory. You can [browse the repository](https://sourceforge.net/p/g3d/code/HEAD/tree/) from the top of tree or revision history. Full Library ------------------- You can check out the entire library (10 GB) anonymously using: ~~~~~~~~ svn co svn://svn.code.sf.net/p/g3d/code/ g3d ~~~~~~~ ...or with a SourceForge username using: ~~~~~~~~ svn co --username=USERNAME svn+ssh://USERNAME@svn.code.sf.net/p/g3d/code/ g3d ~~~~~~~~ ...or you can check out just the subdirectories that you need. For example `svn://svn.code.sf.net/p/g3d/code/G3D10` is just the library source code, without the large asset packs. If you use the svn `https://` protocol and receive errors such as `svn: E175002: Unexpected HTTP status 504 'Gateway Time-out'`, just run `svn cleanup` and then `svn update` to continue. This should not happen with the `svn://` protocol. For reference when performing a partial checkout, the top level directory structure is: *********************************************************************** * g3d * * | * * +-- G3D10 * * | * * +-- data10 * * | | * * | +-- common * * | +-- game * * | '-- research * * | * * '-- www * *********************************************************************** Minimum Download --------------------- G3D includes common asset files for making games, demos, and research projects, as well as for its own sample programs and automated tests. The asset packs are large, so they are in a separate subdirectory tree from the source code. The minimal installation (about 300 MB) to be able to run the sample programs is: ~~~~~~~~ bash svn co --depth immediates https://svn.code.sf.net/p/g3d/code/ g3d svn up --set-depth immediates g3d/data10 svn up --set-depth infinity g3d/G3D10 svn up --set-depth infinity g3d/data10/common ~~~~~~~~ You can then later execute the following from your g3d directory if you want the additional data packs: ~~~~~~~~ bash svn up --set-depth infinity data10/research svn up --set-depth infinity data10/game ~~~~~~~~ Windows Manual ========================================================================== Requirements ------------------------------------------------------------------------- 1. 64-bit Windows 10 or 11 2. [Python 3.10.4](https://www.python.org/ftp/python/3.10.4/python-3.10.4-amd64.exe download="python-3.10.4-amd64.exe") - During installation, check the box to have Python added to your path. This is not the default. 3. Visual Studio 2022, either the Professional or the [free Community version](https://visualstudio.microsoft.com/thank-you-downloading-visual-studio/?sku=Community&channel=Release&version=VS2022&source=VSLandingPage&passive=false&cid=2030 target="_blank") - Select the "C++ Workload" inside the installer - At Tools ==> Options ==> Text Editor ==> File Extension, map the following extensions to the "Microsoft Visual C++" editor: `any`, `geo`, `glsl`, `pix`, `vrt` - (Optional) At Tools ==> Options ==> Text Editor ==> C/C++, select Smart Indenting, Tab Size = 4, and Insert spaces 4. The [TortoiseSVN 1.9.5](https://downloads.sourceforge.net/project/tortoisesvn/1.9.5/Application/TortoiseSVN-1.9.5.27581-x64-svn-1.9.5.msi?r=https%3A%2F%2Ftortoisesvn.net%2Fdownloads.html&ts=1497747106&use_mirror=pilotfiber target="_blank") subversion client - During installation, select the **command line tools** as well as the GUI. This is not the default. 5. A directory for G3D, such as `c:\g3d`, on a disk with 10 GB of free space 6. (Optional) Join the [g3d-users](https://groups.google.com/forum/#!forum/g3d-users target="_blank") Google group to be notified of new features and receive support. Configure & Build ------------------------------------------------------------------------- 1. Set your **system** variable `g3d` to the location that you'd like to be the root of the G3D tree (such as `c:\g3d`). In Windows 10, do this by ⚙ ==> System ==> About ==> System Info ==> Advanced System Settings ==> Environment Variables... (or by searching for "Environment Variables" in the start menu search) 2. Set the **user** environment variable `G3D10DATA` to `%g3d%\G3D10\data-files;%g3d%\data10\common;%g3d%\data10\game;%g3d%\data10\research` 3. Add `%g3d%\G3D10\build\bin` to the **front** of your **user** environment variable `PATH` (so that Windows can find DLLs when launching your own programs) 4. SVN check out `svn://svn.code.sf.net/p/g3d/code/` to `%g3d%` (do not use https, because it will time out). For developer checkout, see 8. 5. At a command prompt in the `%g3d%\G3D10` directory, run: `buildg3d.cmd local` 6. For any project that depends on G3D, make sure to include this property sheet in your project: `%g3d%\G3D10\VisualStudio\props\developer-build-paths.props`. This can be done through the Visual Studio IDE (View ==> Other Windows ==> Property Manager, [Your Project File] ==> Add Existing Property Sheet. Add `%g3d%\G3D10\VisualStudio\props\developer-build-paths.props` and reload Visual Studio). The G3D sample project "starter" includes this property sheet automatically. 7. See the new project guide at http://casual-effects.com/g3d/G3D10/build/manual/guidenewproject.html for information on how to create your own programs that use G3D. 8. If you want to be able to commit changes back to the repo, you have to be added as a developer on SourceForge by Morgan. Once done, you can checkout with: `svn checkout svn+ssh://SVNUSERNAME@svn.code.sf.net/p/g3d/code/ %g3d%` or `svn checkout --username=SVNUSERNAME svn+ssh://USERNAME@svn.code.sf.net/p/g3d/code/ %g3d%` When prompted for your password, use your SourceForge password, unless you've specifically set up SSH keys, in which case it will be your SSH key password. NOTE: if using TortoiseSVN, you will be prompted multiple times for your password during the checkout process. This isn't your password failing, it is Tortoise making multiple separate calls to SVN and not caching your password. You'll later be able to tell it to cache your password. _You can also make a local build on Windows using the Visual Studio IDE once you've configured your environment as described above. Beware that it uses pre-build steps that invoke Python scripts for some generated code files._ macOS ========================================================================= Beware that because macOS video drivers are produced by Apple as part of the operating system and Apple has deprecated open graphics standards, they lag behind the features on Windows by several years. The G3D build on macOS uses legacy support to emulate these features for you. **If you have a choice, we recommend developing on Windows.** On an Intel Mac, you can reboot your machine using Bootcamp to do this on the same hardware and unlock its full graphics potential. Requirements ------------------------------------------------------------------------- 1. OS X 10.12.2 or later 2. [Python 3.10.4](https://www.python.org/downloads/release/python-3104/ target="_blank") 3. LLVM 8.0.0 and clang++, from [Xcode](https://developer.apple.com/xcode/ target="_blank") 4. [yasm 1.3](http://www.macports.org/ports.php?by=name&substr=yasm target="_blank") via macports 5. [Exuberant-ctags](http://www.macports.org/ports.php?by=library&substr=ctags target="_blank") via macports 5. A directory for G3D, such as `~/g3d`, and set a `g3d` environment variable to its path. 6. Consider joining [g3d-users](https://groups.google.com/forum/#!forum/g3d-users target="_blank") Google group to be notified of new features and receive support. Configure & Build ------------------------------------------------------------------------- ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ bash export g3d=### your choice! Frequently: /Users/$USER/g3d ### export G3D10DATA=$g3d/G3D10/data-files:$g3d/data10/common:$g3d/data10/game:$g3d/data10/research export INCLUDE=$g3d/G3D10/external/glew.lib/include:$g3d/G3D10/external/glfw.lib/include:$g3d/G3D10/external/civetweb.lib/include:$g3d/G3D10/external/qrencode.lib/include:$g3d/G3D10/external/zlib.lib/include:$g3d/G3D10/external/physx/include:$g3d/G3D10/G3D-base.lib/include:$g3d/G3D10/G3D-gfx.lib/include:$g3d/G3D10/G3D-app.lib/include:$g3d/G3D10/external/tbb/include:$g3d/G3D10/external/glslang/glslang:$INCLUDE export LIBRARY=$g3d/G3D10/build/lib:$g3d/G3D10/build/bin:$LIBRARY export PATH=$PATH:$g3d/G3D10/bin:$g3d/G3D10/build/bin ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ [Listing [macosvars]: macOS environment variable assignments for `~/.bashrc`] 1. Add the environment variable assignments from Listing [macosvars] to your `~/.bashrc` file 2. Ensure that your `~/.bash_profile` contains the line `source ~/.bashrc` 3. Check out the source tree with: `svn co svn://svn.code.sf.net/p/g3d/code/ $g3d` 4. At a command prompt in the `$g3d/G3D10` directory, run: `./buildg3d lib data tools` 5. See the new project guide at https://casual-effects.com/g3d/G3D10/build/manual/guidenewproject.html for information on how to create your own programs that use G3D. Once you've built G3D, you can compile any of the sample programs or your own by running `icompile` in the directory containing that project. The iCompile script is distributed as part of G3D, so you already have it. You do not need to write Makefiles or Xcode project files unless you _want_ to. Linux ============================================================================ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ bash sudo apt install apt-utils subversion clang doxygen xorg-dev build-essential libgtk-3-dev exuberant-ctags yasm libzip-dev freeglut3-dev lldb ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ [Listing [linuxpkg]: Linux packages required for building G3D]
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ bash export g3d=### your choice! Frequently: /Users/$USER/Projects/g3d ### export G3D10DATA=$g3d/G3D10/data-files:$g3d/data10/common:$g3d/data10/game:$g3d/data10/research export INCLUDE=$g3d/G3D10/external/glew.lib/include:$g3d/G3D10/external/glfw.lib/include:$g3d/G3D10/external/civetweb.lib/include:$g3d/G3D10/external/qrencode.lib/include:$g3d/G3D10/external/zlib.lib/include:$g3d/G3D10/external/physx/include:$g3d/G3D10/G3D-base.lib/include:$g3d/G3D10/G3D-gfx.lib/include:$g3d/G3D10/G3D-app.lib/include:$g3d/G3D10/external/tbb/include:$g3d/G3D10/external/glslang/glslang:$INCLUDE export LIBRARY=$g3d/G3D10/build/lib:$g3d/G3D10/build/bin:$LIBRARY export PATH=$PATH:$g3d/G3D10/bin:$g3d/G3D10/build/bin export LD_LIBRARY_PATH=$g3d/G3D10/build/bin:$LD_LIBRARY_PATH ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ [Listing [linuxvars]: Linux environment variable assignments for `~/.bashrc`] 1. Install the packages from Listing [linuxpkg]. 2. Add the environment variable assignments from Listing [linuxvars] to your `~/.bashrc` file 3. Ensure that your `~/.bash_profile` contains the line `source ~/.bashrc` 4. Restart your Terminal session, or reboot 5. For *anonymous SVN*, check out the source tree with: `svn co svn://svn.code.sf.net/p/g3d/code/ $g3d` For *registered SourceForge* user access, you can instead use: `svn checkout --username= svn+ssh://@svn.code.sf.net/p/g3d/code/ g3d` 6. At a command prompt, run: `cd $g3d/G3D10` `./buildg3d lib data tools` 7. See the new project guide at https://casual-effects.com/g3d/G3D10/build/manual/guidenewproject.html for information on how to create your own programs that use G3D. Once you've built G3D, you can compile any of the sample programs or your own by running `icompile` in the directory containing that project. The icompile script is distributed as part of G3D, so you already have it. You do not need to write Makefiles unless you _want_ to. Advanced ========================================================================== Dependent Developers ----------------------------------------------------------------- Developers using a precompiled G3D build only need Visual Studio or clang++ installed. They do not need the full build system stack. ### Windows 1. Install Visual Studio 2022, either the Professional or the [free Community version](https://visualstudio.microsoft.com/thank-you-downloading-visual-studio/?sku=Community&channel=Release&version=VS2022&source=VSLandingPage&passive=false&cid=2030 target="_blank") - Select the "C++ Workload" inside the installer - At Tools ==> Options ==> Text Editor ==> File Extension, map the following extensions to the "Microsoft Visual C++" editor: `any`, `geo`, `glsl`, `pix`, `vrt` - (Optional) At Tools ==> Options ==> Text Editor ==> C/C++, select Smart Indenting, Tab Size = 4, and Insert spaces 2. (Optional) Join the [g3d-users](https://groups.google.com/forum/#!forum/g3d-users target="_blank") Google group to be notified of new features and receive support. 3. Set the following environment variables. In Windows 10, do this by ⚙ ==> System ==> About ==> System Info ==> Advanced System Settings ==> Environment Variables... (or by searching for "Environment Variables" in the start menu search) - Set `g3d` to root of your precompiled G3D build - Set `G3D10DATA` to `%g3d%\data-files` - Add `%g3d%\bin` to the **front** of your environment variable `PATH` (so that Windows can find DLLs when launching your own programs) 4. For any project that depends on G3D, make sure to include this property sheet in your project: `%g3d%\G3D10\VisualStudio\props\developer-build-paths.props`. This can be done through the Visual Studio IDE (View ==> Other Windows ==> Property Manager, [Your Project File] ==> Add Existing Property Sheet. Add `%g3d%\G3D10\VisualStudio\props\developer-build-paths.props` and reload Visual Studio). The G3D sample project "starter" include this property sheet automatically. ### macOS and Linux 1. Install clang++, and Python 3.10.4 if you wish to use our `icompile` build system for your own programs. 2. Add the environment variable assignments from Listing [macosvars2] to your `~/.bashrc` file 3. Ensure that your `~/.bash_profile` contains the line `source ~/.bashrc` ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ bash export g3d=### root of your precompiled G3D build ### export G3D10DATA=$g3d/data-files export INCLUDE=$g3d/include:$INCLUDE export LIBRARY=$g3d/lib:$g3d/bin:$LIBRARY export PATH=$g3d/bin:$PATH ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ [Listing [macosvars2]: macOS environment variable assignments for `~/.bashrc`] Building Documentation ----------------------------------------------------------------- The G3D documentation for the subversion top of tree is available online at https://casual-effects.com/g3d/G3D10/build/manual/index.html. You can build local copy of the documentation as well if you wish. To do so, you'll need: 1. [Doxygen 1.8.0 or later](http://www.doxygen.org target="_blank") - on Windows, add the install directory to your `PATH` variable - on macOS, add `/Applications/Doxygen.app/Contents/Resources/` to your `PATH` variable 2. LaTeX - use [MikTex](http://miktex.org/ target="_blank") for Windows - for all other platforms, use [TexLive](https://www.tug.org/texlive target="_blank") 3. [Ghostscript](http://pages.cs.wisc.edu/~ghost/ target="_blank") With those tools installed, run `buildg3d doc`.