Alcatel-Lucent nmake Product Builder

[ Eclipse Support Documents ]

Eclipse JDT Support

Using Alcatel-Lucent nmake with Eclipse JDT

This page provides information on using Alcatel-Lucent nmake with the Eclipse JDT. Eclipse JDT (Java Development Tools) is an Eclipse-based IDE for Java development.

Eclipse JDT, project builds, and nmake

Eclipse JDT provides its own built-in Java compiler. This compiler is tightly integrated integrated with Eclipse and JDT, and provides the source indexing that enables powerful IDE features such as refactoring and quick fix. Generally, replacing the integrated JDT compiler with an external compiler such as javac is not recommended, so the javac based nmake :JAVA: assertion would seem of limited usefulness within an Eclipse development environment.

On the other hand, project builds typically involve complex procedures such as source transformations, which are most effectively represented using nmake Makefile constructs such as dependencies and assertions. Furthermore, project level builds (especially production and release builds) are best run outside of Eclipse using fully automated build procedures typically using javac. This approach maximizes build reliability and reproducibility.

These considerations lead us to a hybrid approach where full nmake-based builds are used for project builds outside of Eclipse. Within Eclipse, nmake is used for those portions of the build not using javac. The integrated Java builder is used for build steps involving compilation of Java source into class files, while other build steps are performed using Eclipse external builders configured to run nmake-based sub-builds. Using the Eclipse external builder feature, multiple builders may be configured and set up to run in a defined sequence, with the built-in Java builder (using the integrated Java compiler) configured as one of these steps.

We illustrate the approach with a simple example project consisting of 3 build steps. There is a pre-compilation step, a compilation step, and a post-compilation step, so the project should be representative of a range of actual projects. The pre-compilation step generates Java source using a simple Java preprocessor. In practice, generating Java source is common and has many practical uses, such as IDL stub generation, parser generation, and platform version code adaptation. The compilation step uses javac for standalone project builds and the integrated Eclipse compiler for builds within Eclipse. The post-compilation step generates a jar file from the class files created in the compilation step.

The remainder of this document discusses integration of nmake-based builds and Eclipse in the context of this example project.

Example Java project

The example project structure is:

Makefile
jglob.mk
nmbldr
src/
    java.mk
    jar.mk
    com/alcatel_lucent/nmake/jdt_build_example/pkg_src/
        A.java
        B.java
    com/alcatel_lucent/nmake/jdt_build_example/pkg_gen/
        Makefile
        D.pjava
        E.pjava
        F.pjava
bin/
toolbin/
    jpp
lib/
    example.jar

Following are contents of project Makefiles.

jglob.mk:

/* standard java locations */
JAVAPACKAGEROOT=$(VROOT)/src
JAVACLASSDEST=$(VROOT)/bin
LIBDIR=$(VROOT)/lib

/* jpp preprocessor source dir */
PPKG=com/alcatel_lucent/nmake/jdt_build_example/pkg_gen

/* dont need C compiler--suppress C probe */
CC=

Makefile:

include $(VROOT)/jglob.mk

:MAKE: $(JAVAPACKAGEROOT)/$(PPKG) - $(JAVAPACKAGEROOT)/java.mk - \
       $(JAVAPACKAGEROOT)/jar.mk

src/java.mk:

include $(VROOT)/jglob.mk

:JAVA: com

src/jar.mk:

include $(VROOT)/jglob.mk

$(LIBDIR)/example.jar :JAR: $(JAVACLASSDEST)/com/*.class JARROOT=$(JAVACLASSDEST)

src/com/alcatel_lucent/nmake/jdt_build_example/pkg_gen/Makefile:

/* preprocess source */
include $(VROOT)/jglob.mk

clobber = 1
JPP=$(VROOT)/toolbin/jpp
JFILES = C.java D.java E.java

%.java : %.pjava
        $(JPP) $(>) > $(<)

:ALL: $(JFILES)

As shown in the top level Makefile there are 3 main build steps: preprocessing, compilation, and jar creation. Preprocessor source files have extension .pjava and are kept in the directory containing the pkg_gen package. .pjava preprocessor source files are processed into Java files using the jpp preprocessor. jpp is a simple exemplary preprocessor that copies the Java source file provided as argument to standard output with a comment line added. nmbldr is a script interfacing between Eclipse external builders and nmake. nmbldr was found useful in this example project as a glue script mapping Eclipse builder invocations to nmake runs and is specific to this example. An actual project might modify nmbldr for its needs, create a new script from scratch, or call nmake directly without any intermediary script. Complete source for this project is available in tar archive jex1.tar.gz.

Project setup

The environment needs to be set up before running either a standalone or Eclipse-based build. The Java bin directory containing the javac and jar commands and the nmake product bin directory containing the nmake command should be on the system PATH. Set VPATH to the top level project directory (the directory containing jglob.mk).

Before running a standalone build, install and configure the JavaDeps package if necessary.

Builds outside Eclipse

To build outside of Eclipse, cd to the top level project directory (the directory containing jglob.mk) and type nmake install to do a complete project build. Type nmake recurse clobber to clean up. On Windows, standalone builds may be performed from an SFU/Interix "Korn Shell" terminal window using the SFU/Interix version of nmake.

Standalone builds outside of Eclipse should be working properly before attempting to launch builds from within Eclipse.

Basic project setup in Eclipse

Start Eclipse from the top level project directory created in the previous step, with the PATH and VPATH setup up as described previously. Any workspace may be used for the example project.

Once in Eclipse, set up the Eclipse Java builder to suppress copying certain project specific files to the output directory. Navigate to the Java builder preference page via Window > Preferences > Java > Compiler > Building. Expand the Output folder settings display area. Set field Filtered Resources to value: "*.launch, Makefile, *.mk, *.mo, *.ms, *.pjava". Click OK.

Turn off automatic building using Project > Build Automatically. This provides more control over project builder triggers, useful for demonstration purposes. Automatic building is also possible and triggers a build whenever a resource is saved.

Select File > New > Project > Java Project to set up a new Java project called "jex1p". Set project option "Create project from existing source". Under "Create project from existing source", enter the top level project directory created in the previous section (the directory containing jglob.mk). On the next page of the project creation wizard, on the Source tab, select "Allow output folders for source folders" with default output folder "jex1p/bin". On the Libraries tab, remove example.jar from the build path if listed.

Exit the New Java Project wizard by clicking Finish. Answer yes if Eclipse offers to open the Java perspective after setting up the new project.

Project builder setup

This step configures an Eclipse integrated external builder that performs our first build step--the preprocessor step. The builder should run before the built-in Java Builder. The configuration creates an Eclipse "launch configuration" that invokes the nmbldr shell script (provided in the example package download). nmbldr then runs the appropriate nmake build steps depending upon the specified options and the Eclipse build type.

To set up the builder, bring up the property dialog for project "jex1p" by selecting the project in the Package Explorer and selecting Project > Properties > Builders. Then click New..., select Program, and click OK.

Configure the builder Main tab using values:

Name:nmbldr_pre
Location:${system_path:ksh}
Working Directory:${build_project}
Arguments:nmbldr -p 2 -t ${build_type} -s jpre

The Variables dialog accessed through the Variables button can assist in entering the variables.

On tab Refresh, select "Refresh resources upon completion", "The project containing the selected resource", and "Recursively include sub-folders". On tab Build Options select "Allocate a Console". Select the following "Run the builder" options: "After a Clean", "During Manual Builds", "During auto builds", and "During a Clean". Click OK. The Builders pane of the project properties should now show the two configured project builders--the new nmbldr builder just configured, and the built-in Java Builder. The builders are shown in the order they will be run when a project is updated. nmbldr needs to run before Java Builder so it can generate or update Java files in package pkg_gen. If nmbldr appears after (below)``Java Builder`` in the project list, select it and press the Up button to position it so it appears before (above) Java Builder in the project builder list:

eclipse JDT builders

Select OK to exit this dialog.

Exercise the builders

Select a resource in the example project in the Package Explorer. Select Project > Clean. Check "Clean projects selected below" and choose the example project. Select "Start a build immediately", and click OK. Build output for the preprocessor step should appear on the console. nmbldr is called twice: once with build type clean and then with build type full to perform a full build. nmbldr generates the appropriate nmake build steps for the specified Eclipse build type.

Incremental builds work also. Select Project > Build Project. Since this is an "incremental" build, nmbldr does an nmake "install" only. Nothing should get built since the project is already up-to-date.

Edit a java source file in pkg_src, for example A.java, or a preprocessor file in package pkg_gen, say C.pjava. Now, Build Project should update the minimal set of files needed to bring the project up to date. Enable Project > Build Automatically. Now, incremental builds should occur automatically upon resource save.

External tool setup

nmake build operations may also be configured as Eclipse "External Tools". External tools are run on demand, rather than participating in Eclipse project builds as the project builders do.

In this section we configure an Eclipse "external tool" that performs an nmake Jar full build. Select the project or some resource in the project, and click Run > External Tools > Open External Tools Dialog (Externals Tools... in Eclipse 3.2.1). Click Program, then the "new" button (the leftmost icon in the dialog toolbar) to bring up a tool configuration dialog.

Configure the Main tab using values:

Name:build_jar_full
Location:${system_path:ksh}
Working Directory:${project_loc}
Arguments:nmbldr -p 3 -t full -s jpost

The Variables dialog accessed through the Variables button can assist in entering the variables. On tab Refresh, select "Refresh resources upon completion", "The project containing the selected resource", and "Recursively include sub-folders". In the Common tab, uncheck "Launch in background", and select "Allocate Console". Select Run to run the tool. Eclipse runs the newly defined tool, in the process also incrementally updating the workspace.

After the initial run, select Run > External Tools > build_jar_full to re-run the tool. Alternatively, use the external tools run button in the Workbench toolbar.

If desired, the Jar update step could also be configured as a project builder that runs after the Java compilation step. The procedure is similar to the "nmblder_pre" configuration described above, except: set the Name: field to "nmbldr_post" and set the arguments to: nmbldr -p 2 -t ${build_type} -s jpost. Position this builder so it runs last, after Java Builder in the build sequence.

Notes

  • src and bin are standard directory names traditionally used in Eclipse for Java source and class files.
  • These instructions use generic Eclipse features and are not specific to Eclipse JDT.
  • These instructions have been tested with Eclipse versions 3.2.1 on Solaris and 3.3M6 on linux, using nmake versions lu3.8 and a pre-release version of alu3.9. These instructions have also been tested on Windows XP/SP2 using Eclipse 3.3RC4 with a prerelease version of nmake alu3.9 (SFU/Interix version).
  • Build option "After a Clean" is only necessary on Eclipse 3.2.1.

Issues

  • As configured above, the external builder output appears in the Eclipse console view. The console view is cleared before each builder runs, erasing the output of any previous builder in the build sequence. To work around this you might want to have a builder pause a few seconds after it completes (nmbldr -p option), or direct build output to a file.
  • The same issues with viewpathing and Makefile editing mentioned on the Eclipse CDT setup page are also present here. See that page for more information.
Last Update: Monday,28-Feb-2011 16:27:59 EST