File: palcom/doc/setup/Eclipse-build.txt

Overview of how to build the PalCom projects in Eclipse

1. One-step build of the projects from inside Eclipse

   Please see Eclipse-SVN.txt for information about how to check out
   and import projects into your Eclipse workspace. Project builders
   will be triggered automatically after the import, but some errors
   will remain when they have finished. It may be most convenient for
   you to disable this automatic build (remove the check mark in the
   "Project" menu).

   In order to get rid of the errors, you need to perform one manual
   step: re-building the "dev-lib" project. Right-click on
   dev-lib/build.xml, and choose Run As->Ant build... (three dots). 
   On the Refresh tab, check "Refresh resources upon
   completion" and "The entire workspace". Click Apply and then
   Run. After the dev-lib Ant Build has finished, there should
   be no errors. Enable automatic build again.

   Note: cases have been observed where the initial run of the dev-lib
   Ant script fails with an "out of heap space" error during a
   compilation step. If that occurs, re-run the Ant build..., and this
   time put "-Xmx500M" in the "VM arguments" field on the JRE tab
   before clicking Run. This heap space setting will be saved for
   later runs.

   Section 3 describes in more detail how the different projects are
   built.

2. Building for JVM on the command-line

   If you want to work from the command line, the projects can be
   build for execution on the JVM using

       pal-dev-build -J

   (see Command-line-tools.txt for instructions on how to set up for
   command line execution).
   If you do this, the next time you start up Eclipse, make sure to do
   a Refresh of all projects, to make Eclipse aware of the build you
   did.

3. Building the projects

   3.1 pal-vm

       Notice that if you import the "pal-vm" project, you should also
       make sure to have the CDT plugin installed. See
       Eclipse-install.txt.

   3.2 AST classes for the pal-j compiler

       If you import the pal-j compiler project Backend, its Ant
       script build.xml has to be run for generating the compiler's
       AST classes (defined in JastAdd grammars and aspects). This is
       done automatically after import. You can also choose
       Project->Clean with Backend selected, or right-click on
       build.xml and select Run As->Ant Build.

       When running the Ant script manually, it is recommended to set
       up an Eclipse launch configuration like this: right-click on
       Backend/build.xml, and select Run As->Ant Build... (three
       dots). On the Refresh tab, check "Refresh resources upon
       completion" and "The entire workspace". Click Apply and then
       Run or Close.

   3.3 Pal-J projects

       Pal-J projects are built for the JVM using a combination of two
       tools: the Eclipse compiler and Ant (Pal-VM builds are run from
       the command-line). The Eclipse compiler runs automatically when
       a source file is changed in Eclipse (provided that
       Project->Build Automatically is checked). The generated class
       files end up in the bin directory in each project (which is
       hidden in the Package Explorer view, but can be seen in the
       Navigator).

       Ant scripts, named build.xml, are placed in the project
       directories of some projects. For projects that have JastAdd
       classes, their Ant scripts build those. The Ant script in the
       dev-lib project (dev-lib/build.xml) compiles code for all the
       projects into two JAR files. The JAR files are used by the
       EclipseBrowser, and also when running from the
       command-line. This Ant script can be run by selecting Run
       As->Ant Build, as described for Backend in 3.2.
 
       If you have the Ant tool installed, the Ant scripts can also be
       run from the command-line, by typing "ant" when standing in the
       dev-lib project directory. See http://ant.apache.org/ for
       information about how to install and use Ant.

       The dependencies between the Pal-J projects for the PalCom
       Runtime Environment, for Middleware Managers, for Frameworks
       and for Utilities are illustrated in the figure
       palcom/doc/setup/figures/projects.png. The projects are the
       boxes with filled edges. A project can use classes in all
       projects directly or indirectly referenced in the graph
       (following the arrows one or more steps). These dependencies
       are captured in the Java Build Path settings in each project
       (and thus in the Eclipse .classpath files), in the following
       way: all projects are set to export the projects they depend
       on, and each .classpath file only declares the project's direct
       dependencies in the graph. The projects in the engine box
       without illustrated dependencies contain the pal-vm source code
       and base libraries.

       The pal-jbase project is a JVM implementation of (a subset of)
       the Smalltalk classes in pal-base. It uses the whole JDK,
       because the classes in pal-jbase only run on the JVM. From
       collections and up, the classes should run on both the Pal-VM
       and the JVM. The collections project uses a subset of the JDK
       classes in java.lang, java.io and java.util. The rest of the
       JDK classes are excluded from use in Eclipse (an exclusion
       filter in the file collections/.classpath). For projects above
       collections, you get Access restriction errors in Eclipse if
       you try to use classes from the JDK, except the selected
       classes in java.lang, java.io, and java.util.

       For the Ant scripts, the classpath dependencies are not managed
       on a project-by-project basis. Instead, the combination of all
       source folders and all classpaths are listed in one place, in
       the dev-lib Ant script (dev-lib/build.xml). The path elements
       "palcom.src.path", "application.src.path" and "class.path"
       define the source paths and classpaths.

   2.4 AST classes for Pal-J projects

       The projects mal-layer, communication-layer, function-layer and
       assembly have JastAdd classes. If you import these projects,
       you can re-generate the JastAdd classes by running Ant
       scripts. Re-generation is necessary if you edit JastAdd source
       files (.jadd, .jrag or .ast files). A quick way to re-generate
       all JastAdd classes is to run the jastadd-gen target in
       dev-lib/build.xml.

   2.5 The EclipseBrowser plugin

       If you import the EclipseBrowser plugin, you need the
       jars-plugin project, which exports a generated JAR file used by
       the EclipseBrowser. The JAR file can be re-built by running the
       Ant script EclipseBrowser/build.xml. It is recommended to set
       up a launch configuration with "The entire workspace" chosen on
       the Refresh tab, as described above. Rebuilding the JAR file is
       necessary if you make changes to any of the Pal-J projects,
       discussed under 2.3, while working with the EclipseBrowser.

       Cases have been observed where the jars-plugin project does not
       find the JAR file in Eclipse, even after it has been generated,
       and after refreshing the project (a "missing required library"
       error). A workaround in such a case can be to make a small
       change to jars-plugin/build.properties (just add a space
       somewhere) and save the file. That makes Eclipse see the JAR
       file again.

       For further information about how to set up and use the
       EclipseBrowser, see the documentation files in
       EclipseBrowser/doc.