Virtual Object System/Interreality 3D "s5" See COPYING for license information. This file last updated 10 October 2007. === About === This is the first release of the new Virtual Object System "s5" development branch. This is a ground-up redesign and reimplementation of the VOS platform. The primary purpose of this release is to demonstrate a prototype user interface that is highly flexible, self-documenting, and both keyboard and mouse friendly. Because this is a prototype, it does not have most of the backend features that are planned, including network support, ability to save to files, scripting, etc. The secondary purpose is to lay the ground work for building, packaging and distributing VOS software in a cross-platform manner. Finally, this distribution contains several placeholder "hello world" type test programs and data files. These were written to facilitate development of the build system and/or understanding of certain dependent libraries and will be removed once development of "real" === Building === The VOS build system is based on the Software Construction (SCons) (http://scons.org/) tool. For your convenience, a copy of SCons has been included in the VOS source distribution. SCons and the VOS build scripts require Python (http://python.org/) version 2.4 or later. The SCons build system is used for all supported platforms. As of this writing, VOS has been successfully compiled on: * Microsoft Windows XP using Visual C++ Express (8.0) * Macintosh OS X 10.4 * Debian GNU/Linux 4.0r1 "Etch" (and unstable "Sid" as of Oct. 2007) Visual Studio (voss5.vcproj) and XCode (voss5.xcodeproj) projects are provided for the convenience of users preferring to use an IDE, but these project files are configured to run the provided "scons.py" when it comes time to perform the build. The build system is designed to be require minimal work on your part in terms of installing additional tools and libraries. It should be possible to build VOS requiring only: * A functioning C++ compiler * Python 2.4 * OpenGL and GLU libraries and headers * Platform GUI libraries and headers, one of * Microsoft Platform SDK * OS X Core Frameworks * GTK 2.0 For all other dependencies, the build system is able to automatically download and compile most tools and libraries VOS depends on. These third party tools and libraries are downloaded to and compiled in $BUILDCFG/thirdparty, and installed to $BUILDCFG/thirdparty/stagex. For this reason, the VOS build system may require Internet access to be able to fetch these packages. However, the build system will prefer to use system-installed versions of those tools and libraries where appropriate and available. Building VOS on the command line is easy: $ ./scons.py (on Windows, run "scons.bat") This will do system configuration checks, possibly download and compile dependencies, and actually build VOS. Built programs and libraries will be placed in either the "debug/stage" or "release/stage" directories, unless the DESTDIR option is used to change that directory. Options can be specified on the command line in the form OPTION=value, for example: $ ./scons.py BUILDCFG=release DESTDIR=/usr Available options are: DESTDIR: The root directory of the tree where the compiled binaries will be copied. By default, this is the "stage" subdirectory. BUILDCFG: Determines whether to build with debugging information or optimizations. Also controls whether dependencies are built in debug or release mode. (debug|release) default: debug DOWNLOAD_OPT: Determines how to get third party libraries needed to build Interreality libraries and applications. Format is DOWNLOAD_OPT=package1=option,package2=option Where 'option' is one of: apt-get : prefer to install package using apt-get download : prefer download source tar/zip file bzr : prefer to get source using 'bzr branch' hg : prefer to get source using 'hg clone' For example 'DOWNLOAD_OPT=libpng=apt-get,lightfeather=checkout,epm=download' Otherwise default fallback order is apt-get, download, bzr, hg. download, bzr, and hg each get code from interreality.org. === Running === The default staging directory is "$BUILDCFG/stage" (where $BUILDCFG is one of "debug" or "release" as specified in the build options). Executables, libraries, and header files are copied into "bin", "lib" and "include" subdirectories respectively. In addition, there is the staging directory for third party tools and libraries (dependencies built automatically by the VOS build system) located at "$BUILDCFG/thirdparty/stage". In order to run all programs in the staging directory on Linux, and console programs on OS X, a script "run.sh" is provided which sets up environment variables providing the path to the shared libraries. To use this script simply insert "./run.sh" before the name of the program you wish to run, for example: $ ./run.sh ./vosuiprototype For OS X app bundles and on Windows (where the DLLs are copied to the bin directory) the run.sh script is not necessary. The models in VOS are created using the Blender 3D modeler (http://blender.org). You can export your own models for use with VOS using the blenderExportCOD.py script in the "data" directory. The VOS package will attempt to install the script automatically. If it does not, you can install the script by copying blenderExportCOD.py to Blender's "scripts" directory, and restart Blender if it is running. This will add an entry "VOS COD" to the "Exports" menu of Blender. The script supports both "preview" and "save" modes. The preview mode exports to a temporary file and lauches VOS to view the file with a single click. In order for preview to work, the script must be able to find VOS. On Linux, this means vosuiprototype must be in the system $PATH. On Windows, this means accessing a registry key (HKEY_LOCAL_MACHINE\Software\vosuiprototype) pointing to VOS (this is set up automatically by the VOS Windows installer). On OS X, the VOS application is found via automatic registration as the handler for the "COD" file type. === Installing === The preferred method of installing VOS is to build an installer package appropriate for your operating system, and then install that package. On OS X, the app bundles created by the build system are entirely self contained. It is sufficient to copy the app bundle from the staging directory to your Applications folder. VOS also can build a disk image (dmg) suitable for distribution: $ ./scons.py BUILDCFG=release release/build/src/app/uiprototype/voss5.dmg On Linux, VOS uses the Easy Software Products Package Manager (epm) (http://www.easysw.com/epm/) to support for multiple Linux packaging formats from a single package description file (voss5.list). For example, to build a Debian package use: $ fakeroot epm -f deb voss5 $ su -c dpkg -i linux-2.6-x86_64/voss5-0.1-linux-2.6-x86_64.deb Alternately, you can create RPMs: $ epm -f rpm voss5 $ su -c rpm -i linux-2.6-x86_64/voss5-0.1-linux-2.6-x86_64.rpm There is also a "portable" package format: $ epm -f portable voss5 $ su -c linux-2.6-x86_64/voss5.install On Windows, VOS uses the Windows Installer XML (WiX) tool. ... The WiX file hasn't been written yet. === Next Steps === Futher documentation is located in the "doc" directory. For questions, problems, comments or are interested in contributing to VOS, subscribe to the VOS discussion/development mailing list: http://interreality.org/cgi-bin/mailman/listinfo/vos-d You can also chat with the VOS developers on the #vos IRC channel on irc.freenode.net. Finally, you can always find the latest version of VOS on the Interreality Project web page: http://interreality.org Have fun! - Peter Amstutz