/[gentoo]/xml/htdocs/doc/en/java.xml
Gentoo

Contents of /xml/htdocs/doc/en/java.xml

Parent Directory Parent Directory | Revision Log Revision Log


Revision 1.35 - (show annotations) (download) (as text)
Sun Oct 15 22:03:16 2006 UTC (8 years, 2 months ago) by nightmorph
Branch: MAIN
Changes since 1.34: +4 -74 lines
File MIME type: application/xml
Removed java keywords section now that it's all stable, per nichoj's request on IRC

1 <?xml version="1.0" encoding="UTF-8"?>
2 <!-- $Header: /var/cvsroot/gentoo/xml/htdocs/doc/en/java.xml,v 1.34 2006/10/08 22:52:16 nightmorph Exp $ -->
3 <!DOCTYPE guide SYSTEM "/dtd/guide.dtd">
4
5 <guide link="/doc/en/java.xml">
6 <title>Gentoo Java Guide</title>
7
8 <author title="Author">
9 <mail link="nichoj@gentoo.org">Joshua Nichols</mail>
10 </author>
11 <author title="Author">
12 <mail link="karltk@gentoo.org">Karl Trygve Kalleberg</mail>
13 </author>
14 <author title="Editor">
15 <mail link="nightmorph@gentoo.org">Joshua Saddler</mail>
16 </author>
17
18 <abstract>
19 This guide will introduce you to Java and explain how to use Java with Gentoo
20 Linux.
21 </abstract>
22
23 <!-- The content of this document is licensed under the CC-BY-SA license -->
24 <!-- See http://creativecommons.org/licenses/by-sa/2.5 -->
25 <license/>
26
27 <version>0.11</version>
28 <date>2006-10-15</date>
29
30 <chapter>
31 <title>What is Java?</title>
32 <section>
33 <title>Overview</title>
34 <body>
35
36 <p>
37 Java is a programming language developed by engineers of Sun Microsystems. The
38 language is object-oriented and designed to run on multiple platforms without
39 the need of recompiling code for each platform. Although Java can be compiled
40 as a native program, much of Java's popularity can be attributed to its
41 portability, along with other features such as garbage collection. To make
42 platform independence possible the Java compiler compiles the Java code to an
43 intermediate representation called "Java bytecode" that runs on a JRE (Java
44 Runtime Environment) and not directly on the operating system.
45 </p>
46
47 <p>
48 In order to run Java bytecode, one needs to have a JRE (Java Runtime
49 Environment) installed. A JRE provides core libraries, a platform dependent
50 Java Virtual Machine, plug-ins for browsers, among other things. A JDK (Java
51 Development Kit) adds programming tools, such as a bytecode compiler and a
52 debugger.
53 </p>
54
55 </body>
56 </section>
57 </chapter>
58
59 <chapter>
60 <title>Before You Begin</title>
61 <section>
62 <title>Existing installs</title>
63 <body>
64
65 <p>
66 For existing installs, regardless of if you have installed anything Java
67 before, make sure you have followed the <uri
68 link="/proj/en/java/java-upgrade.xml">Java Upgrade Guide</uri>.
69 </p>
70
71 </body>
72 </section>
73 <section>
74 <title>New installs</title>
75 <body>
76
77 <p>
78 New installs should require no further preparation.
79 </p>
80
81 </body>
82 </section>
83 </chapter>
84
85 <chapter>
86 <title>Installing a Virtual Machine</title>
87 <section>
88 <title>The choices</title>
89 <body>
90
91 <p>
92 Gentoo provides numerous Runtime Environments (JREs) and Development Kits
93 (JDKs). Among the current choices, we have:
94 </p>
95
96 <table>
97 <tr>
98 <th>Vendor</th>
99 <th>JDK</th>
100 <th>JRE</th>
101 </tr>
102 <tr>
103 <ti>The Blackdown Java Kit</ti>
104 <ti>dev-java/blackdown-jdk</ti>
105 <ti>dev-java/blackdown-jre</ti>
106 </tr>
107 <tr>
108 <ti>Sun's Java Kit</ti>
109 <ti>dev-java/sun-jdk</ti>
110 <ti>dev-java/sun-jre-bin</ti>
111 </tr>
112 <tr>
113 <ti>The IBM Java Kit</ti>
114 <ti>dev-java/ibm-jdk-bin</ti>
115 <ti>dev-java/ibm-jre-bin</ti>
116 </tr>
117 <tr>
118 <ti>The Compaq Java Kit for Alpha/Linux/GNU</ti>
119 <ti>dev-java/compaq-jdk</ti>
120 <ti>dev-java/compaq-jre</ti>
121 </tr>
122 <tr>
123 <ti>BEA WebLogic's J2SE Development Kit</ti>
124 <ti>dev-java/jrockit-jdk-bin</ti>
125 </tr>
126 </table>
127
128 <!--
129 TODO: list free implementations?
130 note about not drop-in replacements
131 kaffe/sablevm/gcj/jamvm
132 -->
133 <p>
134 The default for Java 1.4 is the Blackdown JRE/JDK pair, as it is freely
135 ("free as in beer") available without any registration fuss.
136 </p>
137
138 <p>
139 JREs and JDKs from Sun, IBM, and BEA are generally faster, but getting them
140 is a bit more work, as you are required to read and accept their license before
141 downloading (IBM additionally requires you to register).
142 </p>
143
144 </body>
145 </section>
146 <section>
147 <title>Installing a JRE/JDKs</title>
148 <body>
149
150 <p>
151 To install your profile's default JDK, you can run <c>emerge virtual/jdk</c>.
152 Or to install your profile's default JRE, you can <c>emerge virtual/jre</c>.
153 </p>
154
155 <p>
156 In recent events, Sun has relicensed their JDK and JRE under a more Linux
157 distro friendly license. As a result, Sun releases Java 1.5 and onwards are
158 freely downloadable, without any further hassle.
159 </p>
160
161 <note>
162 A JDK also includes a JRE, so if you install a JDK you shouldn't have to also
163 have to install a JRE.
164 </note>
165
166 </body>
167 </section>
168 <section>
169 <title>Installing fetch-restricted virtual machines</title>
170 <body>
171
172 <p>
173 As already mentioned, some of the JDKs and JREs require you to jump through a
174 few hoops before installing. Simply emerge the packages as you normally would.
175 The ebuilds will then instruct you where to go and what to download.
176 </p>
177
178 <p>
179 You should download the indicated file(s) into
180 <path>/usr/portage/distfiles</path>. Once there, you can rerun the emerge
181 command, at which point the JRE/JDK will be begin to install.
182 </p>
183
184 </body>
185 </section>
186 </chapter>
187
188 <chapter>
189 <title>Configuring your virtual machine</title>
190 <section>
191 <title>Overview</title>
192 <body>
193
194 <p>
195 Gentoo has the ability to have multiple JDKs and JREs installed without causing
196 conflicts.
197 </p>
198
199 <p>
200 Using the <c>java-config</c> tool, you can set the system-wide default
201 (provided you have root access). Users can also use <c>java-config</c> to set
202 up their own personal default.
203 </p>
204
205 <note>
206 You can also use <e>eselect</e> to change the system and user vm. See
207 <c>eselect java-vm help</c>.
208 </note>
209
210 </body>
211 </section>
212 <section>
213 <title>Setting a default virtual machine</title>
214 <body>
215
216 <p>
217 Running the command <c>java-config --list-available-vms</c> will give you a
218 list of all JREs and JDKs installed on your system. Here is an example of
219 output:
220 </p>
221
222 <pre caption="Listing available VMs">
223 # <i>java-config --list-available-vms</i>
224 The following VMs are available for generation-2:
225 1) Blackdown JDK 1.4.2.03 [blackdown-jdk-1.4.2]
226 2) Blackdown JRE 1.4.2.03 [blackdown-jre-1.4.2]
227 3) Blackdown 32bit JRE 1.4.2.03 [emul-linux-x86-java-1.4.2]
228 4) Sun 32bit JRE 1.5.0.08 [emul-linux-x86-java-1.5]
229 5) Kaffe 1.1.7 [kaffe]
230 *) Sun JDK 1.5.0.08 [sun-jdk-1.5]
231 </pre>
232
233 <p>
234 The <e>*</e> indicates this is the current active vm (system-vm or user-vm when
235 set). The name in the brackets (<e>[]</e>) is the handle or ID for that
236 particular VM. You use the handle or the number to <c>java-config
237 --set-system-vm</c>. Here is an example of how to set the system VM.
238 </p>
239
240 <pre caption="Setting the System VM">
241 <comment>(By handle (preferred))</comment>
242 # <i>java-config --set-system-vm blackdown-jdk-1.4</i>
243 Now using blackdown-jdk-1.4 as your generation-2 system JVM
244 <comment>(By number)</comment>
245 # <i>java-config --set-system-vm 6</i>
246 Now using sun-jdk-1.5 as your generation-2 system JVM
247 </pre>
248
249 <p>
250 As a regular user, you can use <c>java-config --set-user-vm</c>.
251 </p>
252
253 <note>
254 You no longer have to <c>source</c> the profile for updates to the user/system
255 VM take place.
256 </note>
257
258 </body>
259 </section>
260 <section id="preferred-vm">
261 <title>Preferred VM</title>
262 <body>
263
264 <p>
265 While merging Java packages, the VM can and will be switched as necessary.
266 </p>
267
268 <p>
269 Because of the wide variety of available VMs, we do not have the resources to
270 test and verify every package works on all of them. So to ensure that every
271 packages merges smoothly, we have defined a list of <e>default/supported
272 VMs</e> per arch. You can find them in
273 <path>/usr/share/java-config/config/jdk-defaults.conf</path>. When you are
274 merging a Java package, and it detects one of the VM in that file is installed,
275 it will automatically use that VM, instead of the system-vm.
276 </p>
277
278 <p>
279 The merge time VM switching is also needed when, for example, your system-vm is
280 set a 1.4 VM and the package you are merging requires a 1.5 VM. While merging
281 it will use the preferred 1.5 VM, leaving your system-vm choice intact.
282 </p>
283
284 <p>
285 Of course, Gentoo is all about choice, so you can override these defaults in
286 <path>/etc/java-config-2/build/jdk.conf</path> and have complete control over
287 which VM will get used. Some examples:
288 </p>
289
290 <pre caption="Example /etc/java-config-2/build/jdk.conf">
291 <comment>(I always want it to use a sun-jdk, ie sun-jdk-1.4 for 1.4, sun-jdk-1.5 for 1.5, etc)</comment>
292 *=sun-jdk
293 </pre>
294
295 <pre caption="Example /etc/java-config-2/build/jdk.conf">
296 <comment>(Always use sun-jdk-1.5 wherever possible, except for when a 1.4 or 1.3 VM is explicitly required)</comment>
297 *=sun-jdk-1.5
298 </pre>
299
300 <pre caption="Example /etc/java-config-2/build/jdk.conf">
301 <comment># For 1.3 I prefer sun-jdk 1.4 but when it is not available, use ibm-jdk-bin,
302 # For 1.4, use blackdown-jdk, and for 1.5, use sun-jdk </comment>
303 1.3=sun-jdk-1.4 ibm-jdk-bin
304 1.4=blackdown-jdk
305 1.5=sun-jdk
306 </pre>
307
308 <warn>
309 You do not have to edit this file. If you change these options to use a
310 unsupported VM, things could possibly break. Bugs reported with a unsupported
311 VM won't be prioritized as much as bugs present within supported VMs.
312 </warn>
313
314 </body>
315 </section>
316 </chapter>
317
318 <chapter>
319 <title>Compilers</title>
320 <section>
321 <body>
322
323 <p>
324 The standard Java compiler used for building is javac, which comes with each
325 JDK. In addition to configuring the VM used at build time, it is also possible
326 configure which compiler is used. Essentially, you define a list your
327 preference for which compiler to use in
328 <path>/etc/java-config-2/build/compilers.conf</path>.
329 </p>
330
331 <pre caption="/etc/java-config-2/build/compilers.conf">
332 # If the ebuild supports it
333 # it will check the COMPILERS var front to back and
334 # use the first compiler that is installed
335
336 COMPILERS="ecj-3.1 jikes javac"
337 </pre>
338
339 <p>
340 Some compilers don't support all possible -target and -source arguments.
341 Therefore, each compiler in the list is checked to see if it can support the
342 desired -source/-target. javac will work in all cases, so if no other suitable
343 compiler is found, it will be used instead.
344 </p>
345
346 <p>
347 More details about each compiler are provided below:
348 </p>
349
350 <table>
351 <tr>
352 <th>Name</th>
353 <th>Handle</th>
354 <th>Package</th>
355 <th>Description</th>
356 </tr>
357 <tr>
358 <ti>javac</ti>
359 <ti>javac</ti>
360 <ti>N/A</ti>
361 <ti>
362 This is the default compiler that will be used, and comes with each JDK.
363 </ti>
364 </tr>
365 <tr>
366 <ti>jikes</ti>
367 <ti>jikes</ti>
368 <ti>dev-java/jikes</ti>
369 <ti>
370 Jikes was originally developed by IBM. Anecdotally, it is generally quicker
371 than javac. Note however, that it is more pedantic, and will fail under a
372 few circumstances where javac has no issue. It also does not support Java
373 1.5 syntax yet.
374 </ti>
375 </tr>
376 <tr>
377 <ti>Eclipse Compiler for Java</ti>
378 <ti>ecj-3.1</ti>
379 <ti>=dev-java/eclipse-ecj-3.1*</ti>
380 <ti>
381 ECJ is the compiler used by the Eclipse software development kit. It is
382 very full featured, and is pretty fast. It does support Java 1.5 syntax.
383 </ti>
384 </tr>
385 </table>
386
387 </body>
388 </section>
389 </chapter>
390
391 <chapter>
392 <title>Setting a default CLASSPATH</title>
393 <section>
394 <body>
395
396 <warn>
397 The options explained in this section should be considered deprecated and will
398 most likely be removed in the future. We strongly recommend against using
399 these, because your Java projects or application should ideally manage their
400 own classpaths. If you choose to specify a default CLASSPATH, some applications
401 may behave unexpectedly, because classes they weren't expecting would be on the
402 classpath.
403 </warn>
404
405 <p>
406 <c>java-config</c> can also be used to set a system-wide default CLASSPATH, as
407 well a user-specific default CLASSPATH.
408 </p>
409
410 <p>
411 First, you will want to list available Java libraries installed on your system
412 that might want to be put in your CLASSPATH. Here is an example of output:
413 </p>
414
415 <pre caption="Listing classes">
416 # <i>java-config --list-available-packages</i>
417 [xerces-2] The next generation of high performance, fully compliant XML parsers in the Apache Xerces family (/usr/share/xerces-2/package.env)
418 [junit] Simple framework to write repeatable tests (/usr/share/junit/package.env)
419 [bsh] BeanShell: A small embeddable Java source interpreter (/usr/share/bsh/package.env)
420 [bcel] The Byte Code Engineering Library: analyze, create, manipulate Java class files (/usr/share/bcel/package.env)
421 [log4j] A low-overhead robust logging package for Java (/usr/share/log4j/package.env)
422 ...
423 </pre>
424
425 <p>
426 Again, the names in brackets (<e>[]</e>) are the IDs that you have to pass to
427 <c>java-config --set-system-classpath</c>. Here is an example:
428 </p>
429
430 <pre caption="Setting classpaths">
431 # <i>java-config --set-system-classpath log4j,xerces-2</i>
432 </pre>
433
434 <note>
435 The current directory (<path>.</path>) will not be part of the system
436 classpath, as that should be added in your system's login profile.
437 </note>
438
439 <p>
440 You will have to update your environment by logging out, then in again or
441 sourcing <path>/etc/profile</path>.
442 </p>
443
444 <p>
445 For users, <c>java-config --set-user-classpath</c> will create
446 <path>~/.gentoo/java-env-classpath</path>, which you should then source from
447 your shell's profile.
448 </p>
449
450 <pre caption="Sourcing user specific classpath">
451 <i>if [[ -f "${HOME}/.gentoo/java-env-classpath" ]]; then
452 source ${HOME}/.gentoo/java-env-classpath
453 fi</i>
454 </pre>
455
456 <p>
457 If you really want a system wide or user default classpath you can add
458 something like the following to your shell's profile. But we would advise
459 against it.
460 </p>
461
462 <pre caption="Setting classpath">
463 # <i>export CLASSPATH="${CLASSPATH}:$(java-config --classpath log4j,xerces-2)"</i>
464 </pre>
465
466 </body>
467 </section>
468 </chapter>
469
470 <chapter>
471 <title>Java Browser Plug-ins</title>
472 <section>
473 <title>Installing a plug-in</title>
474 <body>
475
476 <p>
477 You can install a Java plug-in for your web browser by emerging a Java VM with
478 the <c>nsplugin</c> USE flag set.
479 </p>
480
481 <note>
482 <c>nsplugin</c> is not available for all architectures. Check for available
483 plug-ins on your arch before trying to install a VM by running <c>emerge -pv
484 &lt;java-vm&gt;</c>.
485 </note>
486
487 <p>
488 Portage will allow you to install multiple versions of Java plug-ins, though
489 only one will be used by your browser. You can check the list of available
490 plug-ins by running:
491 </p>
492
493 <pre caption="Viewing available plug-ins">
494 # <i>eselect java-nsplugin list</i>
495 [1] sun-jre-bin-1.5
496 [2] blackdown-jre-1.4.2
497 </pre>
498
499 <p>
500 In this example, <c>sun-jre-bin</c> is selected for the browser plug-in.
501 </p>
502
503 <pre caption="Selecting a plug-in">
504 # <i>eselect java-nsplugin sun-jre-bin-1.5</i>
505 </pre>
506
507 <p>
508 Verify that the correct plug-in was selected:
509 </p>
510
511 <pre caption="Verifying the correct plug-in">
512 # <i>eselect java-nsplugin list</i>
513 [1] sun-jre-bin-1.5 current
514 [2] blackdown-jre-1.4.2
515 </pre>
516
517 <p>
518 Java.com also provides a link to <uri
519 link="http://java.com/en/download/installed.jsp">verify your installed
520 plug-in</uri>. Additionally, if you are using a Mozilla-based browser, you can
521 verify your Java plug-in by typing <c>about:plugins</c> into the address bar.
522 </p>
523
524 </body>
525 </section>
526 <section>
527 <title>Plug-ins on multilib systems</title>
528 <body>
529
530 <p>
531 If you are running a mixed 64-bit and 32-bit multilib system (for example, on AMD64),
532 you can have both 64-bit and a 32-bit Java plug-ins installed.
533 </p>
534
535 <p>
536 First, check which plug-ins are available:
537 </p>
538
539 <pre caption="Viewing available plug-ins">
540 # <i>eselect java-nsplugin list</i>
541 Available 32-bit Java browser plugins
542 [1] emul-linux-x86-java-1.4.2
543 [2] emul-linux-x86-java-1.5
544 Available 64-bit Java browser plugins
545 [1] blackdown-jdk-1.4.2
546 [2] blackdown-jre-1.4.2
547 </pre>
548
549 <p>
550 You can select a 32-bit plug-in for a 32-bit browser (for example,
551 <c>firefox-bin</c>), and you can select a 64-bit plug-in for your 64-bit
552 browser (for example, <c>konqueror</c>).
553 </p>
554
555 <pre caption="Selecting plug-ins">
556 # <i>eselect java-nsplugin set 32bit emul-linux-x86-java-1.4.2</i>
557 # <i>eselect java-nsplugin set 64bit blackdown-jdk-1.4.2</i>
558 </pre>
559
560 <p>
561 Verify the correct plug-ins were selected:
562 </p>
563
564 <pre caption="Verifying the correct plug-ins">
565 # <i>eselect java-nsplugin list</i>
566 Available 32-bit Java browser plugins
567 [1] emul-linux-x86-java-1.4.2 current
568 [2] emul-linux-x86-java-1.5
569 Available 64-bit Java browser plugins
570 [1] blackdown-jdk-1.4.2 current
571 [2] blackdown-jre-1.4.2
572 </pre>
573
574 </body>
575 </section>
576 </chapter>
577
578 <chapter>
579 <title>USE flags for use with Java</title>
580 <section>
581 <title>Setting USE flags</title>
582 <body>
583
584 <p>
585 For more information regarding USE flags, refer to the <uri
586 link="/doc/en/handbook/handbook-x86.xml?part=2&amp;chap=2">USE flags</uri>
587 chapter from the Gentoo Handbook.
588 </p>
589
590 </body>
591 </section>
592 <section>
593 <title>The flags</title>
594 <body>
595
596 <ul>
597 <li>The <b>java</b> flag adds support for Java in a variety of programs</li>
598 <li>
599 The <b>nsplugin</b> flag adds support for Mozilla-like browsers (including
600 Firefox). You will need this for viewing Java applets in your Mozilla-like
601 browser.
602 </li>
603 <li>
604 The <b>source</b> flag installs a zip of the source code of a package.
605 This is traditionally used for IDEs to 'attach' source to the libraries you
606 are using.
607 </li>
608 <li>
609 For Java packages, the <b>doc</b> flag will build API documentation using
610 javadoc.
611 </li>
612 </ul>
613
614 </body>
615 </section>
616 </chapter>
617
618 <chapter>
619 <title>Additional resources</title>
620 <section>
621 <title>Off-line resources</title>
622 <body>
623
624 <ul>
625 <li>java-config man page</li>
626 <li><c>java-config --help</c></li>
627 </ul>
628
629 </body>
630 </section>
631 <section>
632 <title>Online resources</title>
633 <body>
634
635 <ul>
636 <li>
637 The <uri link="http://www.gentoo.org/proj/en/java/">Java Project
638 Page</uri>
639 </li>
640 <li>
641 The <uri
642 link="http://news.gmane.org/gmane.linux.gentoo.java">gentoo-java</uri>,
643 <uri
644 link="http://news.gmane.org/gmane.linux.gentoo.user">gentoo-user</uri>, and
645 <uri
646 link="http://news.gmane.org/gmane.linux.gentoo.devel">gentoo-dev</uri>
647 mailing list archives
648 </li>
649 <li>#gentoo and #gentoo-java on irc.freenode.net</li>
650 <li>
651 <uri
652 link="http://en.wikipedia.org/wiki/Java_programming_language">Wikipedia's
653 entry for Java</uri>
654 </li>
655 </ul>
656
657 </body>
658 </section>
659 </chapter>
660 </guide>

  ViewVC Help
Powered by ViewVC 1.1.20