/[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.45 - (show annotations) (download) (as text)
Wed Oct 7 18:25:46 2009 UTC (4 years, 10 months ago) by nightmorph
Branch: MAIN
Changes since 1.44: +2 -6 lines
File MIME type: application/xml
the default for java 1.6 is not necessarily sun, it varies by arch. pp64 has ibm, for example. so punt that sentence from the guide, as the instructions on installing the default jdk/jre for one's profile are immediately below it in the next chapter. thanks to betelgeuse on IRC

1 <?xml version="1.0" encoding="UTF-8"?>
2 <!-- $Header: /var/cvsroot/gentoo/xml/htdocs/doc/en/java.xml,v 1.44 2009/10/07 18:14:31 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.20</version>
28 <date>2009-10-07</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, plugins 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>BEA WebLogic's J2SE Development Kit</ti>
119 <ti>dev-java/jrockit-jdk-bin</ti>
120 </tr>
121 </table>
122
123 <!--
124 TODO: list free implementations?
125 note about not drop-in replacements
126 kaffe/sablevm/gcj/jamvm
127 -->
128 </body>
129 </section>
130 <section>
131 <title>Installing a JRE/JDKs</title>
132 <body>
133
134 <p>
135 To install your profile's default JDK, you can run <c>emerge virtual/jdk</c>.
136 Or to install your profile's default JRE, you can <c>emerge virtual/jre</c>.
137 </p>
138
139 <p>
140 In recent events, Sun has relicensed their JDK and JRE under a more Linux
141 distro friendly license. As a result, Sun releases Java 1.5 and onwards are
142 freely downloadable, without any further hassle.
143 </p>
144
145 <note>
146 A JDK also includes a JRE, so if you install a JDK you shouldn't have to also
147 have to install a JRE.
148 </note>
149
150 </body>
151 </section>
152 <section>
153 <title>Installing fetch-restricted virtual machines</title>
154 <body>
155
156 <p>
157 Some of the JDKs and JREs require you to jump through a few hoops before
158 installing. Simply emerge the packages as you normally would. The ebuilds will
159 then instruct you where to go and what to download.
160 </p>
161
162 <p>
163 You should download the indicated file(s) into
164 <path>/usr/portage/distfiles</path>. Once there, you can rerun the emerge
165 command, at which point the JRE/JDK will be begin to install.
166 </p>
167
168 </body>
169 </section>
170 </chapter>
171
172 <chapter>
173 <title>Configuring your virtual machine</title>
174 <section>
175 <title>Overview</title>
176 <body>
177
178 <p>
179 Gentoo has the ability to have multiple JDKs and JREs installed without causing
180 conflicts.
181 </p>
182
183 <p>
184 Using the <c>java-config</c> tool, you can set the system-wide default
185 (provided you have root access). Users can also use <c>java-config</c> to set
186 up their own personal default.
187 </p>
188
189 <note>
190 You can also use <e>eselect</e> to change the system and user vm. See
191 <c>eselect java-vm help</c>.
192 </note>
193
194 </body>
195 </section>
196 <section>
197 <title>Setting a default virtual machine</title>
198 <body>
199
200 <p>
201 Running the command <c>java-config --list-available-vms</c> will give you a
202 list of all JREs and JDKs installed on your system. Here is an example of
203 output:
204 </p>
205
206 <pre caption="Listing available VMs">
207 # <i>java-config --list-available-vms</i>
208 The following VMs are available for generation-2:
209 1) Blackdown JDK 1.4.2.03 [blackdown-jdk-1.4.2] <comment>(Build Only)</comment>
210 2) Blackdown JRE 1.4.2.03 [blackdown-jre-1.4.2] <comment>(Build Only)</comment>
211 3) IcedTea6-bin 1.4.1 [icedtea6-bin]
212 4) Sun JDK 1.5.0.20 [sun-jdk-1.5] <comment>(Build Only)</comment>
213 *) Sun JDK 1.6.0.16 [sun-jdk-1.6]
214 </pre>
215
216 <note>
217 VMs marked as Build Only may contain security vulnerabilities and/or be EOL.
218 Gentoo recommends not setting these VMs as either your system or user VM.
219 Please see <uri link="java.xml#build-only">Build Only VM</uri> for more
220 information.
221 </note>
222
223 <p>
224 The <e>*</e> indicates this is the current active vm (system-vm or user-vm when
225 set). The name in the brackets (<e>[]</e>) is the handle or ID for that
226 particular VM. You use the handle or the number to <c>java-config
227 --set-system-vm</c>. Here is an example of how to set the system VM.
228 </p>
229
230 <pre caption="Setting the System VM">
231 <comment>(By handle (preferred))</comment>
232 # <i>java-config --set-system-vm blackdown-jdk-1.4</i>
233 Now using blackdown-jdk-1.4 as your generation-2 system JVM
234 WARNING: blackdown-jdk-1.4 is marked as a build-only JVM. Using this vm is not recommended.
235 <comment>(By number)</comment>
236 # <i>java-config --set-system-vm 5</i>
237 Now using sun-jdk-1.6 as your generation-2 system JVM
238 </pre>
239
240 <p>
241 As a regular user, you can use <c>java-config --set-user-vm</c>.
242 </p>
243
244 <note>
245 You no longer have to <c>source</c> the profile for updates to the user/system
246 VM take place.
247 </note>
248
249 </body>
250 </section>
251 <section id="build-only">
252 <title>Build Only VM</title>
253 <body>
254
255 <p>
256 Some virtual machines are flagged as build-only due to being EOL and/or
257 containing security vulnerabilities. These virtual machines will not
258 automatically be used by Gentoo for the running of applications using Gentoo
259 launchers but will still be available for use by Gentoo's build environment as
260 some packages may require them for building. The setting of these virtual
261 machines as either your system or user VM is strongly discouraged as these VMs
262 will then be used when running the <path>/usr/bin/{java,javac,..}</path>
263 executables and will also be used by any packages not using Gentoo's launcher
264 scripts.
265 </p>
266
267 </body>
268 </section>
269 <section id="preferred-vm">
270 <title>Preferred VM</title>
271 <body>
272
273 <p>
274 While merging Java packages, the VM can and will be switched as necessary.
275 </p>
276
277 <p>
278 Because of the wide variety of available VMs, we do not have the resources to
279 test and verify every package works on all of them. So to ensure that every
280 packages merges smoothly, we have defined a list of <e>default/supported
281 VMs</e> per arch. You can find them in
282 <path>/usr/share/java-config-2/config/jdk-defaults.conf</path>. When you are
283 merging a Java package, and it detects one of the VM in that file is installed,
284 it will automatically use that VM, instead of the system-vm.
285 </p>
286
287 <p>
288 The merge time VM switching is also needed when, for example, your system-vm is
289 set a 1.4 VM and the package you are merging requires a 1.5 VM. While merging
290 it will use the preferred 1.5 VM, leaving your system-vm choice intact.
291 </p>
292
293 <p>
294 Of course, Gentoo is all about choice, so you can override these defaults in
295 <path>/etc/java-config-2/build/jdk.conf</path> and have complete control over
296 which VM will get used. Some examples:
297 </p>
298
299 <pre caption="Example /etc/java-config-2/build/jdk.conf">
300 <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>
301 *=sun-jdk
302 </pre>
303
304 <pre caption="Example /etc/java-config-2/build/jdk.conf">
305 <comment>(Always use sun-jdk-1.5 wherever possible, except for when a 1.4 or 1.3 VM is explicitly required)</comment>
306 *=sun-jdk-1.5
307 </pre>
308
309 <pre caption="Example /etc/java-config-2/build/jdk.conf">
310 <comment># For 1.3 I prefer sun-jdk 1.4 but when it is not available, use ibm-jdk-bin,
311 # For 1.4, use blackdown-jdk, and for 1.5, use sun-jdk </comment>
312 1.3=sun-jdk-1.4 ibm-jdk-bin
313 1.4=blackdown-jdk
314 1.5=sun-jdk
315 </pre>
316
317 <warn>
318 You do not have to edit this file. If you change these options to use a
319 unsupported VM, things could possibly break. Bugs reported with a unsupported
320 VM won't be prioritized as much as bugs present within supported VMs.
321 </warn>
322
323 </body>
324 </section>
325 </chapter>
326
327 <chapter>
328 <title>Compilers</title>
329 <section>
330 <body>
331
332 <p>
333 The standard Java compiler used for building is javac, which comes with each
334 JDK. In addition to configuring the VM used at build time, it is also possible
335 configure which compiler is used. Essentially, you define a list your
336 preference for which compiler to use in
337 <path>/etc/java-config-2/build/compilers.conf</path>.
338 </p>
339
340 <pre caption="/etc/java-config-2/build/compilers.conf">
341 # If the ebuild supports it
342 # it will check the COMPILERS var front to back and
343 # use the first compiler that is installed
344
345 COMPILERS="ecj-3.1 jikes javac"
346 </pre>
347
348 <p>
349 Some compilers don't support all possible -target and -source arguments.
350 Therefore, each compiler in the list is checked to see if it can support the
351 desired -source/-target. javac will work in all cases, so if no other suitable
352 compiler is found, it will be used instead.
353 </p>
354
355 <p>
356 More details about each compiler are provided below:
357 </p>
358
359 <table>
360 <tr>
361 <th>Name</th>
362 <th>Handle</th>
363 <th>Package</th>
364 <th>Description</th>
365 </tr>
366 <tr>
367 <ti>javac</ti>
368 <ti>javac</ti>
369 <ti>N/A</ti>
370 <ti>
371 This is the default compiler that will be used, and comes with each JDK.
372 </ti>
373 </tr>
374 <tr>
375 <ti>jikes</ti>
376 <ti>jikes</ti>
377 <ti>dev-java/jikes</ti>
378 <ti>
379 Jikes was originally developed by IBM. Anecdotally, it is generally quicker
380 than javac. Note however, that it is more pedantic, and will fail under a
381 few circumstances where javac has no issue. It also does not support Java
382 1.5 syntax yet.
383 </ti>
384 </tr>
385 <tr>
386 <ti>Eclipse Compiler for Java</ti>
387 <ti>ecj-3.1</ti>
388 <ti>=dev-java/eclipse-ecj-3.1*</ti>
389 <ti>
390 ECJ is the compiler used by the Eclipse software development kit. It is
391 very full featured, and is pretty fast. It does support Java 1.5 syntax.
392 </ti>
393 </tr>
394 </table>
395
396 </body>
397 </section>
398 </chapter>
399
400 <chapter>
401 <title>Setting a default CLASSPATH</title>
402 <section>
403 <body>
404
405 <warn>
406 The options explained in this section should be considered deprecated and will
407 most likely be removed in the future. We strongly recommend against using
408 these, because your Java projects or application should ideally manage their
409 own classpaths. If you choose to specify a default CLASSPATH, some applications
410 may behave unexpectedly, because classes they weren't expecting would be on the
411 classpath.
412 </warn>
413
414 <p>
415 <c>java-config</c> can also be used to set a system-wide default CLASSPATH, as
416 well a user-specific default CLASSPATH.
417 </p>
418
419 <p>
420 First, you will want to list available Java libraries installed on your system
421 that might want to be put in your CLASSPATH. Here is an example of output:
422 </p>
423
424 <pre caption="Listing classes">
425 # <i>java-config --list-available-packages</i>
426 [xerces-2] The next generation of high performance, fully compliant XML parsers in the Apache Xerces family (/usr/share/xerces-2/package.env)
427 [junit] Simple framework to write repeatable tests (/usr/share/junit/package.env)
428 [bsh] BeanShell: A small embeddable Java source interpreter (/usr/share/bsh/package.env)
429 [bcel] The Byte Code Engineering Library: analyze, create, manipulate Java class files (/usr/share/bcel/package.env)
430 [log4j] A low-overhead robust logging package for Java (/usr/share/log4j/package.env)
431 ...
432 </pre>
433
434 <p>
435 Again, the names in brackets (<e>[]</e>) are the IDs that you have to pass to
436 <c>java-config --set-system-classpath</c>. Here is an example:
437 </p>
438
439 <pre caption="Setting classpaths">
440 # <i>java-config --set-system-classpath log4j,xerces-2</i>
441 </pre>
442
443 <note>
444 The current directory (<path>.</path>) will not be part of the system
445 classpath, as that should be added in your system's login profile.
446 </note>
447
448 <p>
449 You will have to update your environment by logging out, then in again or
450 sourcing <path>/etc/profile</path>.
451 </p>
452
453 <p>
454 For users, <c>java-config --set-user-classpath</c> will create
455 <path>~/.gentoo/java-env-classpath</path>, which you should then source from
456 your shell's profile.
457 </p>
458
459 <pre caption="Sourcing user specific classpath">
460 <i>if [[ -f "${HOME}/.gentoo/java-env-classpath" ]]; then
461 source ${HOME}/.gentoo/java-env-classpath
462 fi</i>
463 </pre>
464
465 <p>
466 If you really want a system wide or user default classpath you can add
467 something like the following to your shell's profile. But we would advise
468 against it.
469 </p>
470
471 <pre caption="Setting classpath">
472 # <i>export CLASSPATH="${CLASSPATH}:$(java-config --classpath log4j,xerces-2)"</i>
473 </pre>
474
475 </body>
476 </section>
477 </chapter>
478
479 <chapter>
480 <title>Java Browser Plugins</title>
481 <section>
482 <title>Installing a plugin</title>
483 <body>
484
485 <p>
486 You can install a Java plugin for your web browser by emerging a Java VM with
487 the <c>nsplugin</c> USE flag set.
488 </p>
489
490 <note>
491 <c>nsplugin</c> is not available for all architectures. Check for available
492 plugins on your arch before trying to install a VM by running <c>emerge -pv
493 &lt;java-vm&gt;</c>.
494 </note>
495
496 <p>
497 Portage will allow you to install multiple versions of Java plugins, though
498 only one will be used by your browser. You can check the list of available
499 plugins by running:
500 </p>
501
502 <pre caption="Viewing available plugins">
503 # <i>eselect java-nsplugin list</i>
504 [1] sun-jre-bin-1.6
505 [2] icedtea6-bin
506 </pre>
507
508 <p>
509 In this example, <c>sun-jre-bin</c> is selected for the browser plugin.
510 </p>
511
512 <pre caption="Selecting a plugin">
513 # <i>eselect java-nsplugin set sun-jre-bin-1.6</i>
514 </pre>
515
516 <p>
517 Verify that the correct plugin was selected:
518 </p>
519
520 <pre caption="Verifying the correct plugin">
521 # <i>eselect java-nsplugin list</i>
522 [1] sun-jre-bin-1.6 current
523 [2] icedtea6-bin
524 </pre>
525
526 <p>
527 Java.com also provides a link to <uri
528 link="http://java.com/en/download/installed.jsp">verify your installed
529 plugin</uri>. Additionally, if you are using a Mozilla-based browser, you can
530 verify your Java plugin by typing <c>about:plugins</c> into the address bar.
531 </p>
532
533 </body>
534 </section>
535 <section>
536 <title>Plugins on multilib systems</title>
537 <body>
538
539 <p>
540 If you are running a mixed 64-bit and 32-bit multilib system (for example, on
541 AMD64), you can use 64-bit and 32-bit Java plugins. Unless you have a pressing
542 need to run 32-bit Java applications, we recommend using native 64-bit plugins
543 on 64-bit web browsers.
544 </p>
545
546 <p>
547 There are several native 64-bit browser plugins available. The default JDK/JRE
548 pair, <c>sun-jdk</c> and <c>sun-jre-bin</c>, both include browser plugins. Just
549 emerge one of them with the <c>nsplugin</c> USE flag enabled.
550 </p>
551
552 <pre caption="Installing a 64-bit plugin">
553 # <i>echo "dev-java/sun-jre-bin nsplugin" >> /etc/portage/package.use</i>
554 # <i>emerge sun-jre-bin</i>
555 </pre>
556
557 <p>
558 To use a 32-bit plugin on a 32-bit browser, you will need to emerge
559 <c>emul-linux-x86-java</c> with the <c>nsplugin</c> USE flag enabled.
560 </p>
561
562 <pre caption="Installing a 32-bit plugin">
563 # <i>echo "app-emulation/emul-linux-x86-java nsplugin" >> /etc/portage/package.use</i>
564 # <i>emerge emul-linux-x86-java</i>
565 </pre>
566
567 <p>
568 Next, check which plugins are available:
569 </p>
570
571 <pre caption="Viewing available plugins">
572 # <i>eselect java-nsplugin list</i>
573 Available 32-bit Java browser plugins
574 [1] emul-linux-x86-java-1.5
575 [2] emul-linux-x86-java-1.6
576 Available 64-bit Java browser plugins
577 [1] icedtea6-bin
578 [2] sun-jre-bin-1.6
579 </pre>
580
581 <p>
582 Now select the right plugin for your browsers:
583 </p>
584
585 <pre caption="Selecting plugins">
586 <comment>(Choose the plugins for 32-bit and 64-bit browsers)</comment>
587 # <i>eselect java-nsplugin set 32bit emul-linux-x86-java-1.6</i>
588 # <i>eselect java-nsplugin set 64bit sun-jre-bin-1.6</i>
589 </pre>
590
591 <p>
592 Verify the correct plugin was selected:
593 </p>
594
595 <pre caption="Verifying the correct plugin">
596 # <i>eselect java-nsplugin list</i>
597 Available 32-bit Java browser plugins
598 [1] emul-linux-x86-java-1.5
599 [2] emul-linux-x86-java-1.6 current
600 Available 64-bit Java browser plugins
601 [1] icedtea6-bin
602 [2] sun-jre-bin-1.6 current
603 </pre>
604
605 </body>
606 </section>
607 </chapter>
608
609 <chapter>
610 <title>USE flags for use with Java</title>
611 <section>
612 <title>Setting USE flags</title>
613 <body>
614
615 <p>
616 For more information regarding USE flags, refer to the <uri
617 link="/doc/en/handbook/handbook-x86.xml?part=2&amp;chap=2">USE flags</uri>
618 chapter from the Gentoo Handbook.
619 </p>
620
621 </body>
622 </section>
623 <section>
624 <title>The flags</title>
625 <body>
626
627 <ul>
628 <li>The <b>java</b> flag adds support for Java in a variety of programs</li>
629 <li>
630 The <b>nsplugin</b> flag adds support for Mozilla-like browsers (including
631 Firefox). You will need this for viewing Java applets in your Mozilla-like
632 browser.
633 </li>
634 <li>
635 The <b>source</b> flag installs a zip of the source code of a package.
636 This is traditionally used for IDEs to 'attach' source to the libraries you
637 are using.
638 </li>
639 <li>The <b>jce</b> flag adds support for the Java Cryptography Engine</li>
640 <li>
641 For Java packages, the <b>doc</b> flag will build API documentation using
642 javadoc.
643 </li>
644 </ul>
645
646 </body>
647 </section>
648 </chapter>
649
650 <chapter>
651 <title>Additional resources</title>
652 <section>
653 <title>Off-line resources</title>
654 <body>
655
656 <ul>
657 <li>java-config man page</li>
658 <li><c>java-config --help</c></li>
659 </ul>
660
661 </body>
662 </section>
663 <section>
664 <title>Online resources</title>
665 <body>
666
667 <ul>
668 <li>
669 The <uri link="http://www.gentoo.org/proj/en/java/">Java Project
670 Page</uri>
671 </li>
672 <li>
673 The <uri
674 link="http://news.gmane.org/gmane.linux.gentoo.java">gentoo-java</uri>,
675 <uri
676 link="http://news.gmane.org/gmane.linux.gentoo.user">gentoo-user</uri>, and
677 <uri
678 link="http://news.gmane.org/gmane.linux.gentoo.devel">gentoo-dev</uri>
679 mailing list archives
680 </li>
681 <li>
682 <uri link="irc://irc.gentoo.org/gentoo">#gentoo</uri> and <uri
683 link="irc://irc.gentoo.org/gentoo-java">#gentoo-java</uri> on IRC
684 </li>
685 <li>
686 <uri
687 link="http://en.wikipedia.org/wiki/Java_programming_language">Wikipedia's
688 entry for Java</uri>
689 </li>
690 <li>
691 If you have suggestions or questions regarding this document, please email
692 the Gentoo Java team: <mail>java@gentoo.org</mail>
693 </li>
694 </ul>
695
696 </body>
697 </section>
698 </chapter>
699 </guide>

  ViewVC Help
Powered by ViewVC 1.1.20