0N/AWorking on OpenJDK using NetBeans
0N/A This note describes how to work on the OpenJDK from NetBeans. We've
0N/A provided several NetBeans projects as starting points. Below we'll
0N/A describe how to use them, as well as how to create your own.
0N/A In addition to the source bundle for Open JDK, you'll need to download
0N/A and install copies of the JDK and of NetBeans 6. And if you want to run
0N/A tests on the JDK (you do want to run tests, right?), you'll need to
0N/A install the jtreg test harness.
0N/A In this note, when pathnames are not fully specified, they should be
0N/A interpreted as being relative to the directory containing this README
0N/A and the NetBeans projects themselves.
0N/A The JDK build process is largely make-based, and is not
0N/A exceptionally tolerant of pathnames with spaces in them (such as
0N/A "Program Files". Please be sure to install everything in a
0N/A directories whose paths don't have any spaces!
0N/A You've probably done this a million times. Download and install it
0N/A Downloading the OpenJDK sources
0N/A Since you're reading this, d you've already downloaded the OpenJDK
0N/A source bundle. Later in this document we'll refer to the location
0N/A where you installed the Open JDK sources as *install-dir*.
0N/A Downloading a pre-built, JDK 7
0N/A This will be necessary to do builds of some of the projects. In
0N/A general, you want to download and install a pre-built JDK that
0N/A corresponds to the OpenJDK sources you download. Building the entire
0N/A OpenJDK depends on a few parts of the pre-built JDK. Get this from
0N/A Note: For working on certain projects, like JMX and JConsole, you
0N/A may find convenient to use a pre-built version of JDK 7 (or
0N/A OpenJDK) rather than building your own. This will allow you
0N/A to build only that part of the OpenJDK sources which correspond
0N/A Yep, NetBeans *6*. Nope, not FCS'd yet. We're on the edge here,
0N/A enjoy it! Get the latest working development build of NetBeans 6
0N/A "jtreg" is the test harness for running OpenJDK's regression tests.
0N/A NetBeans comes with ant, but if you use a separately-installed copy
0N/A please make sure that it is at least version 1.7.0.
0N/A Building OpenJDK is hard and complex. No, strike that. While it's not
0N/A exactly "easy", we've got it down to *relatively* small set of
0N/A properties you need to set.
0N/A The NetBeans projects provided here share a fair amount of common
0N/A structure. They share properties values where it makes sense. Each
0N/A project loads properties from these properties files, in this order
0N/A (${basedir} refers to the directory containing a particular NetBeans
0N/A project.) The first time a property defined determines value: it is
0N/A *not* overridden if it is read from properties files read later. The net
0N/A result is that by carefully choosing where to define a property, you can
0N/A have it for a specific project, all uses of a specific project (useful
0N/A if you work on multiple copies of the OpenJDK sources), all projects, or
0N/A only projects in a specific sandbox.
0N/A With that in mind, please set the following properties. Presuming you
0N/A want the same values for all your work, set them in
0N/A Set to the location where you installed JDK 7.
0N/A Set to the location where you installed jtreg.
0N/A Some of the projects invoke "make", since they compile native code.
0N/A installed where to make. Change the paths to fit your particular
0N/A The trailing '\' are important, so that make gets the above as a
0N/A single set of options.
0N/A You might want to add additional additional options: see the README
0N/A for the project you're using for more information. And see
0N/A to read much more about building the JDK.
0N/A Windows-specific configuration
0N/A First, please note that the entire JDK cannot currently be built on
0N/A Windows platforms. This will likely limit your ability to build
0N/A make-based projects. See
0N/A for full information on issues with building on the Windows platform.
0N/A That said, there are two ways to work with the Windows-required settings
0N/A for the Microsoft tools. Either:
0N/A * Set environment variables values in Windows
0N/A Doing so means accessing the System control panel in Windows, and
0N/A setting the environment variables there.
0N/A By doing so, you can launch NetBeans by double-clicking its icon,
0N/A and the environment variable values will be available.
0N/A * Set environment variable values in a shell
0N/A Doing so means adding the settings to an init file (
e.g. .bashrc,
0N/A .cshrc, etc.) or a file that you source before running NetBeans. In
0N/A this case, you'll have to launch NetBeans from the command line in a
0N/A shell in which you've set the environment variables.
0N/A In either case, the end result should be that the settings are available
0N/A to the make-based build process when it runs from within NetBeans.
0N/A The make-based builds presumes that you're using cygwin, and expects to
0N/A find "make" in c:\cygwin\bin\make. If you've installed cygwin elsewhere,
0N/A set "make" in a properties file.
0N/A Configuring Project Properties
0N/A A note of caution is in order: These are NetBeans *freeform* projects.
0N/A If you use the NetBeans GUI to examine them, things are likely to not
0N/A look "right". Please don't edit them there, please instead use a text
0N/A To build the Open JDK sources, be certain that you are using the "C"
0N/A locale on Unix (R) platforms, or "English (United States)" locale on
0N/APlatforms and architectures, oh my!
0N/A The Open JDK can be built for a variety of operating system platforms
0N/A and hardware architectures. The resulting builds are always placed in a
0N/A directory which contains the platform and architecture as part of the
0N/A pathname, as in *platform*-*arch*. For example, if you build the jdk
0N/A project on a Linux platform running on x86 hardware, the resulting build
0N/A We've provided support for some platforms and architectures in
0N/AProvided NetBeans projects
0N/A This section describes the NetBeans projects that help you work on
0N/A particular parts of the JDK. While they're largely similar in structure
0N/A and should work the way you expect NetBeans projects to work: edit,
0N/A build, test, etc. But there are some differences. They don't all support
0N/A the same targets (
e.g., there's nothing to run in jarzip project).
0N/A Some projects are built by invoking make, since they involve compilation
0N/A of native code or other activities that cannot be done by javac. We call
0N/A these "make-based", and call all others "ant-based".
0N/A specifies what subdirectories of the JDK sources they manipulate, what
0N/A directories contain their tests, whether they use make or ant, etc.
0N/A The very first time you open any one of these projects on set of Open
0N/A JDK sources, NetBeans will scan the entire set of sources, not just
0N/A those for the project you opened. This will take a few minutes, but will
0N/A ensure that Go To Type, Go To Source, and so on work as expected. Later,
0N/A when you open other projects on the same Open JDK sources, there will be
0N/A at most a slight delay.
0N/A There's a README accompanying each project. Most are text files, which
0N/A you can Open in NetBeans, some are HTML files, in which case unless you
0N/A enjoy reading raw HTML, you're better off choosing the *View* menu item
0N/A from the context menu, which will display the README in your web
0N/A Finally, note that these projects were all created by different people,
0N/A and are while some attempt has been made to make them look and behave
0N/A the same, they are maintained separately and will vary somewhat.
0N/A The projects currently provided are:
0N/A jdk (directory "jdk")
0N/A A convenient starting point for the other projects, and from which
0N/A you can build the entire OpenJDK. Please note that depending on your
0N/A hardware, this could take a *very* long time. The results of the
0N/A world (directory "world")
0N/A This project builds both the Hotspot VM and all of JavaSE. Please
0N/A note that pretty much regardless of your hardware, this *will* take
0N/A a long time, and use *lots* of disk space (more than 3GB). The
0N/A results of the build are in
2499N/A *install-dir*/build/*platform*-*arch* and
2499N/A *install-dir*/build/*platform*-*arch*-fastdebug.
0N/A Consult the project's README file for details.
0N/A AWT & Java2d (directory "awt2d")
0N/A For working on AWT and Java2d. Supports running the Font2DTest demo.
0N/A This is a make-based project: In order to build this project, you
0N/A should build the jdk project first, since AWT and Java2d include
0N/A JConsole (directory "jconsole")
0N/A running and debugging JConsole.
0N/A This ant-based project does *not* require that you build the jdk
0N/A project first, provided that you use a pre-built version of JDK 7.
0N/A Java (TM) Management Extensions (JMX(TM)) API (directory "jmx")
0N/A This ant-based project does *not* require that you build the jdk
0N/A project first, provided that you use a pre-built version of JDK 7.
0N/A Jar & Zip (directory "jarzip")
0N/A For working on jar & zip. It builds the zip library (including
0N/A native code), the jar library, and the jar tool. Creates an
0N/A executable jar program in ../build/*platform*-*arch*
/bin/jar.
0N/A This is a make-based project: In order to build this project, you
0N/A should build the jdk project first, since AWT and Java2d include
0N/A Swing (directory "swing")
0N/A running and debugging the SampleTree demo.
0N/A This ant-based project does *not* require that you build the jdk
0N/A project first, provided that you use a pre-built version of JDK 7.
0N/A In addition, there are projects for building the compiler, javadoc,
0N/A and related tools, in the OpenJDK langtools component. These
0N/A projects are separate from those described here, and have their
0N/A own set of guidelines and conventions. For more details, see the
0N/A We use the jtreg test harness, described more fully at
0N/A The OpenJDK tests are in the default Java package, are public classes,
0N/A and have a "static void main(String[] args)" with which they are
0N/A invoked. Some tests are actually shell scripts, which might compile
0N/A code, etc. jtreg is quite flexible.
0N/A To run tests for a project, use *Test Project* from NetBeans. From the
0N/A command line, you can invoke "ant jtreg" on any individual project's
0N/A In either NetBeans of on the command line, jtreg prints summary output
0N/A about the
pass/fail nature of each test. An HTML report of the entire
0N/A In that same JTreport directory are also individual HTML files
0N/A summarizing the test environment, test passes and failures, etc.
0N/A More detail on any individual test is under
0N/A ../build/*platform*-*arch*/jtreg/*ant-project-name*/JTwork.
0N/A test are under the JTwork directory at the same pathname as the test
0N/A itself in a ".jtr" file. For example:
0N/A Sometimes you will see that running jtreg has resulted in a failure.
0N/A This does not always mean that a test has an error in it. Jtreg
0N/A distinguishes between these two cases. There are a number of tests that
0N/A are "ignored", and not run, and these are reported as failures.
0N/A You can run a single test by right clicking on it and choosing *Run
0N/A File* from the context menu. Similarly, you can debug a single test by
0N/A choosing *Debug File*.
0N/A Debugging is enabled by default in ant-based projects, as if
0N/A "-g:lines,vars,source" were given. You can alter these settings via
0N/A entries in one of the configuration properties files. For example:
0N/A To debug a project or test, use NetBeans in the normal way, with *Debug
0N/A Project* or *Debug File*. Note that not all projects provide a target
0N/A that can be debugged, but tests can be debugged.
0N/A You can create Javadoc for any of the projects: just choose *Generate
0N/A Javadoc for Project* from the NetBeans menu. Your default browser will
0N/A open up, displaying the just-generated javadoc.
0N/A Javadoc gets generated into a separate subdirectory for each project.
0N/A For example, the Jar & Zip project's javadoc gets generated in
0N/A Each project can of course be cleaned. Make-based and ant-based projects
0N/A differ a little in what exactly gets cleaned. In both cases, all jtreg
0N/A results and javadoc are removed.
0N/A In ant-based projects, project-specific files as determined by the
0N/A directories that are under ../build/*platform*-*arch*.
0N/A In make-based projects, "make clean" is run in the same directories as
0N/A "make all" is run when building the project.
0N/A Please note that the jdk project is "special" with respect to
0N/A cleaning: in this case, the entire ../build directory is removed.
0N/A Similar for the world project.
0N/ACreating your own NetBeans project
0N/A The project's we've provided are hopefully a useful starting point, but
0N/A chances are that you want to work on something else. This section will
0N/A describe how to select an existing project, and then adapt it to your
0N/A The first consideration is whether or not the code in which you're
0N/A interested needs anything beyond javac and copying of resources to
0N/A build. If so, then you'll need to create a make-based project. If not,
0N/A an ant-based project is possible. See the project descriptions above to
0N/A learn which are make-based, and which are ant-based.
0N/A The second consideration is to consider the files that you'll need. Each
0N/A project is defined by 3 files:
0N/A This is the ant build script. For a make-based project, they tend to
0N/A have a target for "make clean" and another for "make all", each of
0N/A which invokes "make-run" in the same set of directories. Take a look
0N/A For an ant-based project, there might be nothing, with all the work
0N/A overrides the -pre-compile and -post-compile targets that are
0N/A This file defines the directories (and possibly files) that are
0N/A included in and excluded from. Basically, a file is considered to be
0N/A in a project if it is mentioned in the includes list, or is
0N/A contained under a directory mentioned in that list, *unless* it is
0N/A explicitly excluded or is contained under a directory that is
0N/A This file defines a project for NetBeans for a "freeform" project.
0N/A Each declares several entity references, which are used later in the
0N/A an ant-based project. Compare that with
0N/A difference! That's because while the jarzip project is make-based,
0N/A it does not have any platform-specifc native code. Contrast that
0N/A notice that it uses platform-specific entity references.
0N/A In summary, we recommend exploring the given projects, and choosing one
0N/A that most closely suits our needs.
0N/A Example: A project for working on collections
0N/A Let's create a project to work with on the collections classes. There's no native
0N/A code here, so an ant-based project will do. Therefore, the jconsole
0N/A project is a reasonable project to use as a starting point.
0N/A Clone the existing project
0N/A Make a directory for the collections project next to the existing projects:
0N/A Copy files from the jconsole project:
0N/A Change the set of files included in the project
0N/A The collections sources are all under one directory, and we want to include
0N/A them all. The same is true of the tests. So edit
0N/A Notice the trailing "/" in some of those pathnames: that tells NetBeans to
0N/A treat the path as a directory and include (or exclude) everything beneath
0N/A it in the hierarchy. Note also how we include
java/util, but then exclude
0N/A several directories under that which are not related to collections.
0N/A The
build.xml for collections is about as simple as can be. First, change the
0N/A name of the project:
0N/A <project name="collections" default="build" basedir=".">
0N/A Then remove the -pre-compile target from the
build.xml. Change the
0N/A to only contain the collections-related classes. The jar task now looks
0N/A user-visible name, both of which should be changed:
0N/A <name>Collections</name> <!-- Customized -->
0N/A <property name="name">collections</property> <!-- Customized -->
0N/A Inside of <ide-actions>, you'll see actions defined for "run" and
0N/A "debug". The Open JDK sources don't include any interesting Collections
0N/A demos, but leave these here for now: Chances are you'll find or create
0N/A some collections app of your own, and want to run and or debug it.
0N/A Now, open the Collections project in NetBeans. You'll find that it operates
0N/A just like all the other projects.
0N/A If/when you want to have this project run a collections demo, change the run
0N/A for the app. From NetBeans, you should be able to run and debug the app,
0N/A including setting breakpoints in collections code.
0N/AAppendix 1: Customizations
0N/A There are several ways to customize NetBeans projects. These projects
0N/A below apply to most any project.
0N/A Several properties can be user-defined (and several should not be
0N/A user-defined!). There are different properties files read. Some default
0N/A targets can be overridden.
0N/A When projects are started, and when when ant runs (whether from NetBeans
0N/A or the command line), these properties files are loaded in the order
0N/A Recall that with ant, once a property is defined, its value cannot be
0N/A changed, so it's "first one wins".
0N/A To set or change a property for all your projects, put the change into
0N/A regardless of how many copies of the Open JDK sources you have
0N/A Let's say you have 2 copies of the Open JDK sources installed on your
0N/A machine. To set or change a property for only the jconsole projects, but
0N/A for both of them, make the change in
0N/A make the change for only one of them, do it in that project's
0N/A the Open JDK sources. If you want to make a change for a particular
0N/A project, you can do so there. To be sure that you don't ever
0N/A accidentally check it in to the Open JDK sources, you might prefer to
0N/A User-definable Properties
0N/A You can provide your own definitions for the properties listed below. We
0N/A don't recommend overriding the definitions of other properties.
0N/A The following two properties should be set before you try to use the
0N/A projects with NetBeans or ant:
0N/A Default: None. Please set this, normally in
0N/A Default: None. Please set this, normally in
0N/A These options are for configuring the behavior of make:
0N/A for a project which is make-based.
0N/A Default: The right make for the platform, at the normal location, set
0N/A Default: Empty string. Set this to any options you want to pass to
0N/A The remaining options are for use at your discretion:
0N/A Default: lines,vars,source
0N/A Default: Empty string. Some projects will need to set this to
0N/A increase the heap for running javadoc. For example, see the jconsole
0N/A Default: "none". Set this only if your project has packages that
0N/A should be javadoc'd which are outside of those listed in the javadoc
0N/A target's packageset. See the jconsole project for an example.
0N/A Default: None. Set this to a list of tests
and/or directories
0N/A containing regression tests, normally in
0N/A User-overridable Targets
0N/A The following targets are provided for your convenience in customizing
0N/A various standard actions of the build process. The default action for
0N/A each one is to do nothing.
0N/A These come in pairs, allowing your scripts to take some action before or
0N/A after a standard action.
0N/A Runs before any other initialization has been done.
0N/A Runs before after all other initialization has been done.
0N/A Runs before compilation, whether via ant or make. Note that in the
0N/A case of make, it is before the -build-make target has run, not after
0N/A each individual make-run has run.
0N/A Runs after compilation, whether via ant or make.
0N/A Runs before regression tests are run.
0N/A Runs before after regression tests are run.
0N/A In a make-based project, you should override these targets to do the
0N/A build and clean actions required of your project.
0N/A Tests won't run: waiting for lock
0N/A Occasionally when running tests, there will be a delay, followed by a
0N/A Waiting to lock test result cache for
0N/A The workaround is to stop the tests, rm -rf the offending jtreg/<project>
0N/A directory by hand, and re-run the tests.
0N/A Can't run nor debug a single test in the JConsole test
0N/A In most projects, you can run a single test by opening it in the editor,
0N/A and choosing Run File from the context menu. If you try this with the a
0N/A JConsole test, instead you'll see that *all* tests from *all* projects
0N/A are run. The workaround is to not try to run a single JConsole test.
0N/A Debugging is similarly problematic (both running and debugging use the
0N/A same underlying infrastructure).
0N/A If you do Run File a JConsole tests, you can always stop them by pressing
0N/A the stop button in the NetBeans output window. But you'll be surprised to
0N/A learn that they are actually still running in the background. The only
0N/A way out of this situation is to exit NetBeans. A few more tests will run,
0N/A but after restarting NetBeans things will be OK.
0N/A UNIX is a registered trademark in the United States and other countries,
0N/A exclusively licensed through
X/Open Company, Ltd.