This document provides an introduction to the Project Looking Glass
Developer's
Release, Sun's 3D Desktop open source project on java.net. It explains
how to set up a development environment and how to build Project
Looking Glass and 3D applications.
If you haven't yet set up your run-time environment, please refer to Getting started with the Project Looking Glass Developer's Release for information. Verify that your system meets the minimum requirements for running Project Looking Glass.
To develop applications and enhancements to Project Looking Glass you need to install some components and download the Project Looking Glass source.
Project Looking Glass uses the Apache ANT build tool to manage the build process. If you don't already have ANT installed, download the binary distribution from the apache.org web site:
http://ant.apache.org/
The Project Looking Glass Developer's Release source code is available
in the LG3D open source
project on java.net.
If you haven't previously registered
at java.net then you'll need to
create an account before you can download the source code:
The next step is to download the Project Looking
Glass Core Source to the development system that you configured.
Note for Windows users: You can check out the source files using a CVS client for Windows platform. However, you will need to pay a good attention to the case-insensitiveness of Windows files when checking in any file.
It is not necessary to download the Project Looking Glass X11 source in order to build and run Project Looking Glass. If you choose not to download the X11 source, you will be able to run in "dev mode" (using the script lg3d-dev). In this mode, you can run 3D applications but not native X11 applications.
"Session mode" (lg3d-session) and "app mode" (lg3d-app) allow you to run both 3D applications and native X11 applications, but these scripts will only work if you download and build with the X11 source.
To download the Project Looking Glass X11 source, check out a copy of the lg3d-x11 cvs tree and make it a sibling directory of the lg3d-core you just downloaded. Be sure to check out the cvs branch with the same name as the lg3d-core branch.
For example, if your lg3d-core is in /opt/mylg/lg3d-core and its branch name is dev-0-7-0, do the following to check out lg3d-x11:
% cd /opt/mylg
% cvs -d :pserver:username@cvs.dev.java.net:/cvs checkout -r dev-0-7-0 lg3d-x11/platform/arch lg3d-x11
The currently supported values of platform/arch are:
linux/i686
solaris/i86pc (for Solaris x86).
Congratulations! You've finished setting up your build environment and you can now build Project Looking Glass.
Building Project Looking Glass from source is handled by an ANT build file (build.xml) which is located in your lg3d-core directory. Navigate to this directory and run the ant command to build Project Looking Glass:
% cd ~/projects/lg3d/lg3d-coreYou should see output similar to the following:
% ant
Buildfile: build.xml
init:
[mkdir] Created dir: /home/username/projects/lg3d/lg3d-core/build/classes
unpack-x:
[untar] Expanding: /home/username/projects/lg3d/lg3d-core/ext/lg3d-x11.tar.gz into /home/username/projects/lg3d/lg3d-core/ext
compile:
[javac] Compiling 1 source file to /home/username/projects/lg3d/lg3d-core/build-tools
[javac] Compiling 626 source files to /home/username/projects/lg3d/lg3d-core/build/classes
compile-x11:
check-escher:
[javac] Compiling 25 source files to /home/username/projects/lg3d/lg3d-core/build/classes
init:
unpack-x:
native-x11:
[exec] .:/home/username/projects/lg3d/lg3d-core/src/../build/classes
junit-tests:
no-junit-tests:
[echo] Skipping junit tests because junit.jar is not installed in ext-unbundeled
compile-demo-apps:
[javac] Compiling 5 source files to /home/username/projects/lg3d/lg3d-core/build/classes
[copy] Copying 4 files to /home/username/projects/lg3d/lg3d-core/build/classes/org/jdesktop/lg3d/apps/cdviewer/resources
[copy] Copying 1 file to /home/username/projects/lg3d/lg3d-core/build/classes/org/jdesktop/lg3d/apps/tutorial/resources
[copy] Copying 1 file to /home/username/projects/lg3d/lg3d-core/build/classes/org/jdesktop/lg3d/apps/help/resources
jar:
[mkdir] Created dir: /home/username/projects/lg3d/lg3d-core/build/lib
[jar] Building jar: /home/username/projects/lg3d/lg3d-core/build/lib/lg3d-core.jar
all:
BUILD SUCCESSFUL
Total time: 32 seconds
There are three ways to run Project Looking Glass: app mode, session mode,
and dev mode. These modes are described in the Running
Project Looking Glass section of the Getting
started with the
Project Looking Glass Developer's Release document.
The only difference as a developer is that instead of the start-up scripts
residing in
~/projects/lg3d/lg3d-core/bin
, the scripts you will need to use
reside in
~/projects/lg3d/lg3d-core/src/devscripts.
If you are having problems running Project Looking Glass, refer to the Troubleshooting section in Getting started with the Project Looking Glass Developer's Release.
To stay up-to-date with the latest developments in Project Looking Glass, periodically log into the java.net cvs server and update your cvs workspace:
Now that you've successfully built Project Looking Glass, why not read
on and take a quick tour of the lg3d-core/
directory to
familiarize
yourself with the source code?
The Project Looking Glass source code is located in the lg3d-core/src. Here is an overview of the various files in the lg3d-core source CVS repository.
| Directory | Description |
| build/ | The built
files are stored in this directory. |
| build-tools/ | Tools for
building Project Looking Glass. |
| build.xml | The Ant build
control file. |
| ext/ | Various
components released with Project Looking Glass, namely escher (Java
bindings to X11) and a stable build of lg3d-x11. |
| app/ | A directory in
which you can put applications to be deployed on the taskbar. LG3D automatically search for jar files in this directory and adds them to the taskbar (if they are configured correctly). |
| ext-unbundled/ | A directory in
which you can put components not licensed for distribution with Project
Looking Glass (e.g. junit, Java3D loaders, etc.) You can also install
your own build of lg3d-x11 into here instead of using $LGX11HOME. |
| src/ | The root of
the lg3d-core source tree. |
| classes/ | All of the
.java files are here. Refer to the javadocs in the binary bundle in docs/javadoc/api for more information. |
| devscripts/ | The source for various Project Looking Glass development scripts. These utilize classes in the build/ directory. |
| HelloUniverse | Runs the
Java3D rotating cube demo in a Project Looking Glass session. |
| README | Documentation
for some of the scripts in this directory. |
|
Xtest |
A script for
testing Java X11 classes without X11 support. |
| displayserver | Runs the
Display Server. |
| lg3d-dev | Runs a Project
Looking Glass session in a window in an existing X11 desktop (e.g. Gnome, KDE), without X11 app support.
(This is "developer" or "No X" mode). |
|
lg3d-session |
Runs a Project
Looking Glass session in full screen mode, with X11 app support. |
|
lg3d-app |
Runs Project
Looking Glass as a window in an existing X11 desktop (e.g. Gnome, KDE), with X11 app support. |
|
postinstall |
A configuration script for lg3d-app mode which must be run as root before lg3d-app is run. |
| setup | A helper
script used by the other scripts. |
| etc/ | Contains
various configuration files. |
| jz/ | An obsolete
directory. |
| lg3d/ | |
| README | Documentation
for the various lgconfig* files. |
| lgconfig* | Configuration
scripts for the various modes in which Project Looking Glass can be run. |
| logging.properties | Configuration file which controls the verbosity of logging output to the Display Server log file, /var/tmp/lgserver.log |
| displayconfig/ | For the adventerous, this
directory contains files that allow
you run Project Looking Glass in more complex display environments such
as multi-screen, stereo or power walls. The choice of config is
controlled
by the lgconfig.xml. WARNING! Alternate display configurations have not been extensively tested yet! |
| native/org/jdesktop/lg3d/displayserver/fws/x11/ | The C code for
X11 integration. |
| resources/images/ | Assorted
images used by Project Looking Glass. |
| tests/ | Eventually
will hold the test suite for Project Looking Glass. |
| www/ | java.net site
pages and various documentation. |
To request access to the LG3D project:
Project Looking Glass includes some example 3D applications that you can use to learn how to write applications that exploit the 3D nature of the Project Looking Glass 3D desktop environment. You can find these examples in the lg3d-demo-apps project.
See also:
Building and Running Project Looking Glass with NetBeans
Getting started with the Project
Looking Glass
Project Looking Glass Developer's Release
Notes
Contributing
to Project Looking Glass