1 Working on OpenJDK using NetBeans
2 This note describes how to work on the OpenJDK from NetBeans. We've
3 provided several NetBeans projects as starting points. Below we'll
4 describe how to use them, as well as how to create your own.
5
6 Getting Started
7 In addition to the source bundle for Open JDK, you'll need to download
8 and install copies of the JDK and of NetBeans 6. And if you want to run
9 tests on the JDK (you do want to run tests, right?), you'll need to
10 install the jtreg test harness.
11
12 In this note, when pathnames are not fully specified, they should be
13 interpreted as being relative to the directory containing this README
14 and the NetBeans projects themselves.
15
16 The JDK build process is largely make-based, and is not
17 exceptionally tolerant of pathnames with spaces in them (such as
18 "Program Files". Please be sure to install everything in a
19 directories whose paths don't have any spaces!
20
21 Downloading the JDK
22 You've probably done this a million times. Download and install it
23 from http://java.sun.com/javase
24
25 Downloading the OpenJDK sources
26 Since you're reading this, d you've already downloaded the OpenJDK
27 source bundle. Later in this document we'll refer to the location
28 where you installed the Open JDK sources as *install-dir*.
29
30 Downloading a pre-built, JDK 7
31 This will be necessary to do builds of some of the projects. In
32 general, you want to download and install a pre-built JDK that
33 corresponds to the OpenJDK sources you download. Building the entire
34 OpenJDK depends on a few parts of the pre-built JDK. Get this from
35 http://download.java.net/jdk7/binaries
36
37 Note: For working on certain projects, like JMX and JConsole, you
38 may find convenient to use a pre-built version of JDK 7 (or
39 OpenJDK) rather than building your own. This will allow you
40 to build only that part of the OpenJDK sources which correspond
41 to that project.
42
43 NetBeans 6
44 Yep, NetBeans *6*. Nope, not FCS'd yet. We're on the edge here,
45 enjoy it! Get the latest working development build of NetBeans 6
46 from http://netbeans.org
47
48 jtreg
49 "jtreg" is the test harness for running OpenJDK's regression tests.
50 Get it from http://openjdk.java.net/jtreg
51
52 Ant
53 NetBeans comes with ant, but if you use a separately-installed copy
54 please make sure that it is at least version 1.7.0.
55
56 Configuring
57 Building OpenJDK is hard and complex. No, strike that. While it's not
58 exactly "easy", we've got it down to *relatively* small set of
59 properties you need to set.
60
61 The NetBeans projects provided here share a fair amount of common
62 structure. They share properties values where it makes sense. Each
63 project loads properties from these properties files, in this order
64
65 ${basedir}/nbproject/private/build.properties
66 $HOME/.openjdk/${ant.project.name}-build.properties
67 $HOME/.openjdk/build.properties
68 ${basedir}/build.properties
69
70 (${basedir} refers to the directory containing a particular NetBeans
71 project.) The first time a property defined determines value: it is
72 *not* overridden if it is read from properties files read later. The net
73 result is that by carefully choosing where to define a property, you can
74 have it for a specific project, all uses of a specific project (useful
75 if you work on multiple copies of the OpenJDK sources), all projects, or
76 only projects in a specific sandbox.
77
78 With that in mind, please set the following properties. Presuming you
79 want the same values for all your work, set them in
80 $HOME/.openjdk/build.properties.
81
82 * bootstrap.jdk
83 Set to the location where you installed JDK 7.
84
85 * jtreg.home
86 Set to the location where you installed jtreg.
87
88 * make.options
89 Some of the projects invoke "make", since they compile native code.
90 The make.options property is for passing information about what you
91 installed where to make. Change the paths to fit your particular
92 situation:
93
94 make.options=\
95 ALT_BOOTDIR=/home/me/bin/jdk1.6.0 \
96 ALT_BINARY_PLUGS_PATH=/home/me/bin/openjdk-binary-plugs \
97 ALT_JDK_IMPORT_PATH=/home/me/bin/jdk1.7.0 \
98 OPENJDK=true
99
100 The trailing '\' are important, so that make gets the above as a
101 single set of options.
102
103 You might want to add additional additional options: see the README
104 for the project you're using for more information. And see
105 *install-dir*/jdk/make/README-builds.html
106 to read much more about building the JDK.
107
108 Windows-specific configuration
109 First, please note that the entire JDK cannot currently be built on
110 Windows platforms. This will likely limit your ability to build
111 make-based projects. See
112 *install-dir*/jdk/make/README-builds.html
113 for full information on issues with building on the Windows platform.
114
115 That said, there are two ways to work with the Windows-required settings
116 for the Microsoft tools. Either:
117
118 * Set environment variables values in Windows
119 Doing so means accessing the System control panel in Windows, and
120 setting the environment variables there.
121
122 By doing so, you can launch NetBeans by double-clicking its icon,
123 and the environment variable values will be available.
124
125 * Set environment variable values in a shell
126 Doing so means adding the settings to an init file (e.g. .bashrc,
127 .cshrc, etc.) or a file that you source before running NetBeans. In
128 this case, you'll have to launch NetBeans from the command line in a
129 shell in which you've set the environment variables.
130
131 In either case, the end result should be that the settings are available
132 to the make-based build process when it runs from within NetBeans.
133
134 The make-based builds presumes that you're using cygwin, and expects to
135 find "make" in c:\cygwin\bin\make. If you've installed cygwin elsewhere,
136 set "make" in a properties file.
137
138 Configuring Project Properties
139 A note of caution is in order: These are NetBeans *freeform* projects.
140 If you use the NetBeans GUI to examine them, things are likely to not
141 look "right". Please don't edit them there, please instead use a text
142 editor.
143
144 Locale Requirements
145 To build the Open JDK sources, be certain that you are using the "C"
146 locale on Unix (R) platforms, or "English (United States)" locale on
147 Windows.
148
149 Platforms and architectures, oh my!
150 The Open JDK can be built for a variety of operating system platforms
151 and hardware architectures. The resulting builds are always placed in a
152 directory which contains the platform and architecture as part of the
153 pathname, as in *platform*-*arch*. For example, if you build the jdk
154 project on a Linux platform running on x86 hardware, the resulting build
155 will be in:
156
157 *install-dir*/jdk/build/linux-i586
158
159 We've provided support for some platforms and architectures in
160 common/architectures. Add another, if your needs require it.
161
162 Provided NetBeans projects
163 This section describes the NetBeans projects that help you work on
164 particular parts of the JDK. While they're largely similar in structure
165 and should work the way you expect NetBeans projects to work: edit,
166 build, test, etc. But there are some differences. They don't all support
167 the same targets (e.g., there's nothing to run in jarzip project).
168
169 Some projects are built by invoking make, since they involve compilation
170 of native code or other activities that cannot be done by javac. We call
171 these "make-based", and call all others "ant-based".
172
173 They all are configured by way of a build.properties file, which
174 specifies what subdirectories of the JDK sources they manipulate, what
175 directories contain their tests, whether they use make or ant, etc.
176
177 The very first time you open any one of these projects on set of Open
178 JDK sources, NetBeans will scan the entire set of sources, not just
179 those for the project you opened. This will take a few minutes, but will
180 ensure that Go To Type, Go To Source, and so on work as expected. Later,
181 when you open other projects on the same Open JDK sources, there will be
182 at most a slight delay.
183
184 There's a README accompanying each project. Most are text files, which
185 you can Open in NetBeans, some are HTML files, in which case unless you
186 enjoy reading raw HTML, you're better off choosing the *View* menu item
187 from the context menu, which will display the README in your web
188 browser.
189
190 Finally, note that these projects were all created by different people,
191 and are while some attempt has been made to make them look and behave
192 the same, they are maintained separately and will vary somewhat.
193
194 The projects currently provided are:
195
196 jdk (directory "jdk")
197 A convenient starting point for the other projects, and from which
198 you can build the entire OpenJDK. Please note that depending on your
199 hardware, this could take a *very* long time. The results of the
200 build are in *install-dir*/jdk/build/*platform*-*arch*.
201
202 world (directory "world")
203 This project builds both the Hotspot VM and all of JavaSE. Please
204 note that pretty much regardless of your hardware, this *will* take
205 a long time, and use *lots* of disk space (more than 3GB). The
206 results of the build are in
207 *install-dir*/control/build/*platform*-*arch* and
208 *install-dir*/control/build/*platform*-*arch*-fastdebug.
209
210 Consult the project's README file for details.
211
212 AWT & Java2d (directory "awt2d")
213 For working on AWT and Java2d. Supports running the Font2DTest demo.
214
215 This is a make-based project: In order to build this project, you
216 should build the jdk project first, since AWT and Java2d include
217 native code.
218
219 JConsole (directory "jconsole")
220 For working on JConsole. Creates ../dist/lib/jconsole.jar. Supports
221 running and debugging JConsole.
222
223 This ant-based project does *not* require that you build the jdk
224 project first, provided that you use a pre-built version of JDK 7.
225
226 Java (TM) Management Extensions (JMX(TM)) API (directory "jmx")
227 For working on JMX source code. Creates ../dist/lib/jmx.jar.
228
229 This ant-based project does *not* require that you build the jdk
230 project first, provided that you use a pre-built version of JDK 7.
231
232 Jar & Zip (directory "jarzip")
233 For working on jar & zip. It builds the zip library (including
234 native code), the jar library, and the jar tool. Creates an
235 executable jar program in ../build/*platform*-*arch*/bin/jar.
236
237 This is a make-based project: In order to build this project, you
238 should build the jdk project first, since AWT and Java2d include
239 native code.
240
241 Swing (directory "swing")
242 For working on Swing. Creates ../dist/lib/swing.jar. Supports
243 running and debugging the SampleTree demo.
244
245 This ant-based project does *not* require that you build the jdk
246 project first, provided that you use a pre-built version of JDK 7.
247
248 In addition, there are projects for building the compiler, javadoc,
249 and related tools, in the OpenJDK langtools component. These
250 projects are separate from those described here, and have their
251 own set of guidelines and conventions. For more details, see the
252 README files in make/netbeans in the OpenJDK langtools component.
253
254 Running Tests
255 We use the jtreg test harness, described more fully at
256 http://openjdk.java.net/jtreg
257
258 The OpenJDK tests are in the default Java package, are public classes,
259 and have a "static void main(String[] args)" with which they are
260 invoked. Some tests are actually shell scripts, which might compile
261 code, etc. jtreg is quite flexible.
262
263 To run tests for a project, use *Test Project* from NetBeans. From the
264 command line, you can invoke "ant jtreg" on any individual project's
265 build.xml file.
266
267 In either NetBeans of on the command line, jtreg prints summary output
268 about the pass/fail nature of each test. An HTML report of the entire
269 test run is
270
271 ../build/*platform*-*arch*/jtreg/*ant-project-name*/JTreport/report.html
272
273 In that same JTreport directory are also individual HTML files
274 summarizing the test environment, test passes and failures, etc.
275
276 More detail on any individual test is under
277
278 ../build/*platform*-*arch*/jtreg/*ant-project-name*/JTwork.
279
280 For example, details about the awt/Modal/SupportedTest/SupportedTest
281 test are under the JTwork directory at the same pathname as the test
282 itself in a ".jtr" file. For example:
283
284 ../build/*platform*-*arch*/jtreg/*ant-project-name*/JTwork/awt/Modal/SupportedTest/SupportedTest.jtr
285
286 Sometimes you will see that running jtreg has resulted in a failure.
287 This does not always mean that a test has an error in it. Jtreg
288 distinguishes between these two cases. There are a number of tests that
289 are "ignored", and not run, and these are reported as failures.
290
291 You can run a single test by right clicking on it and choosing *Run
292 File* from the context menu. Similarly, you can debug a single test by
293 choosing *Debug File*.
294
295 Debugging
296 Debugging is enabled by default in ant-based projects, as if
297 "-g:lines,vars,source" were given. You can alter these settings via
298 entries in one of the configuration properties files. For example:
299
300 javac.debug=false
301 javac.debuglevel=<debug level options>
302
303 To debug a project or test, use NetBeans in the normal way, with *Debug
304 Project* or *Debug File*. Note that not all projects provide a target
305 that can be debugged, but tests can be debugged.
306
307 Creating Javadoc
308 You can create Javadoc for any of the projects: just choose *Generate
309 Javadoc for Project* from the NetBeans menu. Your default browser will
310 open up, displaying the just-generated javadoc.
311
312 Javadoc gets generated into a separate subdirectory for each project.
313 For example, the Jar & Zip project's javadoc gets generated in
314
315 ../build/*platform*-*arch*/jtreg/*ant-project-name*/javadoc/jarzip
316
317 Cleaning projects
318 Each project can of course be cleaned. Make-based and ant-based projects
319 differ a little in what exactly gets cleaned. In both cases, all jtreg
320 results and javadoc are removed.
321
322 In ant-based projects, project-specific files as determined by the
323 project's build.properties file are removed from the classes and gensrc
324 directories that are under ../build/*platform*-*arch*.
325
326 In make-based projects, "make clean" is run in the same directories as
327 "make all" is run when building the project.
328
329 Please note that the jdk project is "special" with respect to
330 cleaning: in this case, the entire ../build directory is removed.
331 Similar for the world project.
332
333 Creating your own NetBeans project
334 The project's we've provided are hopefully a useful starting point, but
335 chances are that you want to work on something else. This section will
336 describe how to select an existing project, and then adapt it to your
337 needs.
338
339 Considerations
340 The first consideration is whether or not the code in which you're
341 interested needs anything beyond javac and copying of resources to
342 build. If so, then you'll need to create a make-based project. If not,
343 an ant-based project is possible. See the project descriptions above to
344 learn which are make-based, and which are ant-based.
345
346 The second consideration is to consider the files that you'll need. Each
347 project is defined by 3 files:
348
349 * build.xml
350 This is the ant build script. For a make-based project, they tend to
351 have a target for "make clean" and another for "make all", each of
352 which invokes "make-run" in the same set of directories. Take a look
353 at jarzip/build.xml for an example.
354
355 For an ant-based project, there might be nothing, with all the work
356 done via the declaration of properties in the build.properties file.
357 Take a look at jconsole/build.xml for an example, and notice how it
358 overrides the -pre-compile and -post-compile targets that are
359 defined in common/shared.xml (where they are defined to do nothing).
360
361 * build.properties
362 This file defines the directories (and possibly files) that are
363 included in and excluded from. Basically, a file is considered to be
364 in a project if it is mentioned in the includes list, or is
365 contained under a directory mentioned in that list, *unless* it is
366 explicitly excluded or is contained under a directory that is
367 excluded. Take a look awt2d/build.properties for an example.
368
369 * nbproject/project.xml
370 This file defines a project for NetBeans for a "freeform" project.
371 Each declares several entity references, which are used later in the
372 project. For an example, see javadoc/nbproject/project.xml, which is
373 an ant-based project. Compare that with
374 jarzip/nbproject/project.xml, which is make-based. Not much
375 difference! That's because while the jarzip project is make-based,
376 it does not have any platform-specifc native code. Contrast that
377 with awt2d/nbproject/project.xml, which does have native code;
378 notice that it uses platform-specific entity references.
379
380 In summary, we recommend exploring the given projects, and choosing one
381 that most closely suits our needs.
382
383 Example: A project for working on collections
384 Let's create a project to work with on the collections classes. There's no native
385 code here, so an ant-based project will do. Therefore, the jconsole
386 project is a reasonable project to use as a starting point.
387
388 Clone the existing project
389 Make a directory for the collections project next to the existing projects:
390
391 % mkdir -p collections/nbproject
392
393 Copy files from the jconsole project:
394
395 % cp jconsole/build.properties collections
396 % cp jconsole/build.xml collections
397 % cp jconsole/nbproject/project.xml collections/nbproject
398
399 Change the set of files included in the project
400 The collections sources are all under one directory, and we want to include
401 them all. The same is true of the tests. So edit
402 collections/build.properties so that it contains these lines:
403
404 includes=\
405 java/util/
406 excludes=\
407 java/util/Calendar.java,\
408 java/util/jar/,\
409 java/util/logging/,\
410 java/util/prefs/,\
411 java/util/regex/,\
412 java/util/spi/,\
413 java/util/zip/,\
414 **/*-XLocales.java.template
415 jtreg.tests=\
416 java/util/**/*Collection/ \
417 java/util/**/*Map/ \
418 java/util/**/*Set/ \
419 java/util/**/*List/
420
421 Notice the trailing "/" in some of those pathnames: that tells NetBeans to
422 treat the path as a directory and include (or exclude) everything beneath
423 it in the hierarchy. Note also how we include java/util, but then exclude
424 several directories under that which are not related to collections.
425
426 The build.xml for collections is about as simple as can be. First, change the
427 name of the project:
428
429 <project name="collections" default="build" basedir=".">
430
431 Then remove the -pre-compile target from the build.xml. Change the
432 -post-compile target to create collections.jar without any manifest, and
433 to only contain the collections-related classes. The jar task now looks
434 like this:
435
436 <jar destfile="${dist.dir}/lib/collections.jar">
437 <fileset dir="${classes.dir}">
438 <include name="java/util/*.class"/>
439 <exclude name="java/util/Calendar*.class"/>
440 </fileset>
441 </jar>
442
443 Also, change the clean target to remove collections.jar instead of
444 jconsole.jar.
445
446 Now edit project.xml file. NetBeans uses an internal name and a
447 user-visible name, both of which should be changed:
448
449 <name>Collections</name> <!-- Customized -->
450
451 <property name="name">collections</property> <!-- Customized -->
452
453 Inside of <ide-actions>, you'll see actions defined for "run" and
454 "debug". The Open JDK sources don't include any interesting Collections
455 demos, but leave these here for now: Chances are you'll find or create
456 some collections app of your own, and want to run and or debug it.
457
458 Now, open the Collections project in NetBeans. You'll find that it operates
459 just like all the other projects.
460
461 If/when you want to have this project run a collections demo, change the run
462 target in collections/build.xml to invoke it in whatever manner is appropriate
463 for the app. From NetBeans, you should be able to run and debug the app,
464 including setting breakpoints in collections code.
465
466 Appendix 1: Customizations
467 There are several ways to customize NetBeans projects. These projects
468 share a common structure, based on common/shared.xml and
469 common/make.xml. Because of that sharing, some mechanisms described
470 below apply to most any project.
471
472 Several properties can be user-defined (and several should not be
473 user-defined!). There are different properties files read. Some default
474 targets can be overridden.
475
476 Property files
477 When projects are started, and when when ant runs (whether from NetBeans
478 or the command line), these properties files are loaded in the order
479 shown:
480
481 ${basedir}/nbproject/private/build.properties
482 $HOME/.openjdk/${ant.project.name}-build.properties
483 $HOME/.openjdk/build.properties
484 ${basedir}/build.properties
485
486 Recall that with ant, once a property is defined, its value cannot be
487 changed, so it's "first one wins".
488
489 To set or change a property for all your projects, put the change into
490 $HOME/.openjdk/build.properties. This will affect all projects,
491 regardless of how many copies of the Open JDK sources you have
492 installed.
493
494 Let's say you have 2 copies of the Open JDK sources installed on your
495 machine. To set or change a property for only the jconsole projects, but
496 for both of them, make the change in
497 $HOME/.openjdk/${ant.project.name}-build.properties. If you wanted to
498 make the change for only one of them, do it in that project's
499 ${basedir}/build.properties or
500 ${basedir}/nbproject/private/build.properties.
501
502 Note that the ${basedir}/build.properties file is provided as part of
503 the Open JDK sources. If you want to make a change for a particular
504 project, you can do so there. To be sure that you don't ever
505 accidentally check it in to the Open JDK sources, you might prefer to
506 change it in ${basedir}/nbproject/private/build.properties.
507
508 User-definable Properties
509 You can provide your own definitions for the properties listed below. We
510 don't recommend overriding the definitions of other properties.
511
512 The following two properties should be set before you try to use the
513 projects with NetBeans or ant:
514
515 * bootstrap.jdk
516 Default: None. Please set this, normally in
517 $HOME/.openjdk/build.properties.
518
519 * jtreg.home
520 Default: None. Please set this, normally in
521 $HOME/.openjdk/build.properties.
522
523 These options are for configuring the behavior of make:
524
525 * use.make
526 Default: Not set. Set this, normally in ${basedir}/build.properties,
527 for a project which is make-based.
528
529 * make
530 Default: The right make for the platform, at the normal location, set
531 in *install-dir*/jdk/make/netbeans/common/make.xml
532
533 * make.options
534 Default: Empty string. Set this to any options you want to pass to
535 make, normally in ${basedir}/build.properties.
536
537 The remaining options are for use at your discretion:
538
539 * javac.options
540 Default: -Xlint
541
542 * javac.debug
543 Default: true
544
545 * javac.debuglevel
546 Default: lines,vars,source
547
548 * javadoc.options
549 Default: Empty string. Some projects will need to set this to
550 increase the heap for running javadoc. For example, see the jconsole
551 project.
552
553 * javadoc.packagenames
554 Default: "none". Set this only if your project has packages that
555 should be javadoc'd which are outside of those listed in the javadoc
556 target's packageset. See the jconsole project for an example.
557
558 * jtreg.tests
559 Default: None. Set this to a list of tests and/or directories
560 containing regression tests, normally in
561 ${basedir}/build.properties.
562
563 * jtreg.options
564 Default: Empty string. See http://openjdk.java.net/jtreg
565
566 * jtreg.vm.options
567 Default: Empty string. See http://openjdk.java.net/jtreg
568
569 * jtreg.samevm
570 Default: false. See http://openjdk.java.net/jtreg
571
572 User-overridable Targets
573 The following targets are provided for your convenience in customizing
574 various standard actions of the build process. The default action for
575 each one is to do nothing.
576
577 These come in pairs, allowing your scripts to take some action before or
578 after a standard action.
579
580 * -pre-init
581 Runs before any other initialization has been done.
582
583 * -post-init
584 Runs before after all other initialization has been done.
585
586 * -pre-compile
587 Runs before compilation, whether via ant or make. Note that in the
588 case of make, it is before the -build-make target has run, not after
589 each individual make-run has run.
590
591 * -post-compile
592 Runs after compilation, whether via ant or make.
593
594 * -pre-jtreg
595 Runs before regression tests are run.
596
597 * -post-jtreg
598 Runs before after regression tests are run.
599
600 In a make-based project, you should override these targets to do the
601 build and clean actions required of your project.
602
603 * -build-make
604 * -clean-make
605
606 Known Issues
607 Tests won't run: waiting for lock
608 Occasionally when running tests, there will be a delay, followed by a
609 message like this:
610 Waiting to lock test result cache for
611 /tmp/jdk/build/linux-i586/jtreg/jconsole/JTwork for 20 seconds
612 The workaround is to stop the tests, rm -rf the offending jtreg/<project>
613 directory by hand, and re-run the tests.
614
615 Can't run nor debug a single test in the JConsole test
616 In most projects, you can run a single test by opening it in the editor,
617 and choosing Run File from the context menu. If you try this with the a
618 JConsole test, instead you'll see that *all* tests from *all* projects
619 are run. The workaround is to not try to run a single JConsole test.
620 Debugging is similarly problematic (both running and debugging use the
621 same underlying infrastructure).
622
623 If you do Run File a JConsole tests, you can always stop them by pressing
624 the stop button in the NetBeans output window. But you'll be surprised to
625 learn that they are actually still running in the background. The only
626 way out of this situation is to exit NetBeans. A few more tests will run,
627 but after restarting NetBeans things will be OK.
628
629 Attribution
630 UNIX is a registered trademark in the United States and other countries,
631 exclusively licensed through X/Open Company, Ltd.
632