Project Looking Glass Developer's Guide


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.

1. Getting Started
2. Setting up your development environment
3. Download the Project Looking Glass Developer's Release
4. Building Project Looking Glass
5. Configuring for App Mode
6. Running Project Looking Glass
7. Getting the latest Project Looking Glass source code
8. A Quick Tour of the Project Looking Glass Source
9. Contributing to Project Looking Glass
10. Learning how to write 3D applications for Project Looking Glass

1. Getting Started

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.

2. Setting up your development environment

Download and install the development tools

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/

Note: The instructions below assume that you download the ANT binary distribution into /tmp.

After downloading ANT, install it as follows:
  1. First become root:

    % su root
    Password: enter root password
    #

  2. Install Apache ANT:

    # cd /usr/local
    # tar -xzf /tmp/apache-ant-1.6.1-bin.tar.gz

  3. Exit from the root shell:

    # exit
    %

  4. Several environment variables now need to be set. Here's the syntax for bash(1):

    ANT_HOME=/usr/local/apache-ant-1.6.1
    PATH=$ANT_HOME/bin:$PATH

3. Download the Project Looking Glass Developer's Release

The Project Looking Glass Developer's Release source code is available in the LG3D open source project on java.net.

Register at the java.net web site

If you haven't previously registered at java.net then you'll need to create an account before you can download the source code:

  1. Navigate to http://www.java.net and click on the Register link at the top of the page.
  2. Enter your preferred user name and e-mail address and then press the [Register] button.
  3. You'll receive an e-mail message with instructions on how to set a password for your account. Once you've entered your password and accepted the java.net website terms of participation you'll be logged in.
  4. Now navigate to the LG3D project web site.
To browse the Project Looking Glass core source code, click on lg3d-core in the Subprojects section of the LG3D project web site Then click on Version control in the Project  tools section of the side bar. On the right side you'll see the source tree represented as links. You can click on these links to browse the source tree and download individual files for viewing.

Download the Project Looking Glass Core Source

The next step is to download the Project Looking Glass Core Source to the development system that you configured.

  1. First create a directory for the Project Looking Glass project, for example:

    % mkdir -p ~/projects/lg3d
    % cd ~/projects/lg3d


    App mode note: if you plan on using this build to run app mode (lg3d-app), be sure to download into a LOCAL disk partition. Do not use a mounted network partition.

  2. Next, log into the cvs.dev.java.net CVS server:

    % cvs -d :pserver:username@cvs.dev.java.net:/cvs login
    CVS password:
    password

    Substitute username and password with your java.net account information.

  3. Check out the lg3d-core source files:

    % cvs -d :pserver:username@cvs.dev.java.net:/cvs checkout lg3d-core

  4. The lg3d-demo-apps project contains several 3D applications, including the CD Viewer application and some tutorials. The Project Looking Glass desktop requires these files, so check them out:

    % cvs -d :pserver:username@cvs.dev.java.net:/cvs checkout lg3d-demo-apps

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.

Download the Project Looking Glass X11 Source (Optional)

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).

What's Next?

Congratulations! You've finished setting up your build environment and you can now build Project Looking Glass.

4. Building 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-core
% ant

You should see output similar to the following:
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

5. Configuring for App Mode

If you plan on using the script src/devscripts/lg3d-app make sure you have placed your copy of the lg3d-core CVS tree on a local disk partition. Then become the root user and run the following:

# cd ~/projects/lg3d/lg3d-core
# ./postinstall


Then return to being a normal user.

6. Running Project Looking Glass

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.

7. Getting the latest Project Looking Glass source code

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:

  1. Change directory to your ~/projects/lg/lg3d-core directory:

    % cd ~/projects/lg/lg3d-core

  2. Remove the built files for the current version of the source:

    % ant clean

  3. Change directory to your ~/projects/lg directory:

    % cd ~/projects/lg

  4. Now update your workspace with the latest Project Looking Glass source code:

    % cvs -d :pserver:username@cvs.dev.java.net:/cvs update -Pd lg3d-core

    and update the demo applications:

    % cvs -d :pserver:username@cvs.dev.java.net:/cvs update -Pd lg3d-demo-apps

    Substitute username with your java.net username.

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?

8. A Quick Tour of the Project Looking Glass Source

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.

9. Contributing to Project Looking Glass

Learn what it means to contribute

Please read the Contributing to Project Looking Glass document for further information on what it means to contribute, then if you're interested, request access to the LG3D project.

Request access to the LG3D project

To request access to the LG3D project:

  1. If you are not logged into java.net, navigate to http://www.java.net and login by entering your username and password in the fields at the top of the page and pressing the [Login] button.
  2. Navigate to https://lg3d.dev.java.net and bookmark it for future reference. You'll be coming back often!
  3. Click on the Request project membership/role link.
  4. Select the appropriate role:
    - Select Observer if you just want to build Project Looking Glass.
    - Select Developer if you plan to develop new code for Project Looking Glass and want the option to contribute code to the project.
  5. After submitting your request, you will receive an e-mail that contains instructions on how to access the project.
From now on, when you go to the LG3D project web site you will need to login to access the project documents.

10. Learning how to write 3D applications for Project Looking Glass

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


$Revision: 1.19 $ $Date: 2005/06/26 16:03:27 $