/[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.49 - (show annotations) (download) (as text)
Tue Jul 6 11:51:28 2010 UTC (4 years ago) by jkt
Branch: MAIN
Changes since 1.48: +19 -19 lines
File MIME type: application/xml
#325885, speak about the system VM and the merge VM. Patch by Caster.

1 <?xml version="1.0" encoding="UTF-8"?>
2 <!-- $Header: /var/cvsroot/gentoo/xml/htdocs/doc/en/java.xml,v 1.48 2010/03/31 23:38:40 nightmorph Exp $ -->
3 <!DOCTYPE guide SYSTEM "/dtd/guide.dtd">
4
5 <guide>
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.23</version>
28 <date>2010-07-06</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>Sun's Java Kit</ti>
104 <ti>dev-java/sun-jdk</ti>
105 <ti>dev-java/sun-jre-bin</ti>
106 </tr>
107 <tr>
108 <ti>The IBM Java Kit</ti>
109 <ti>dev-java/ibm-jdk-bin</ti>
110 <ti>dev-java/ibm-jre-bin</ti>
111 </tr>
112 <tr>
113 <ti>BEA WebLogic's J2SE Development Kit</ti>
114 <ti>dev-java/jrockit-jdk-bin</ti>
115 </tr>
116 </table>
117
118 <!--
119 TODO: list free implementations?
120 note about not drop-in replacements
121 kaffe/sablevm/gcj/jamvm
122 -->
123 </body>
124 </section>
125 <section>
126 <title>Installing a JRE/JDKs</title>
127 <body>
128
129 <p>
130 To install your profile's default JDK, you can run <c>emerge virtual/jdk</c>.
131 Or to install your profile's default JRE, you can <c>emerge virtual/jre</c>.
132 </p>
133
134 <p>
135 In recent events, Sun has relicensed their JDK and JRE under a more Linux
136 distro friendly license. As a result, Sun Java 1.5 and onwards are
137 freely downloadable, without any further hassle.
138 </p>
139
140 <note>
141 A JDK also includes a JRE, so if you install a JDK you shouldn't have to also
142 have to install a JRE.
143 </note>
144
145 </body>
146 </section>
147 <section>
148 <title>Installing fetch-restricted virtual machines</title>
149 <body>
150
151 <p>
152 Some of the JDKs and JREs require you to jump through a few hoops before
153 installing. Simply emerge the packages as you normally would. The ebuilds will
154 then instruct you where to go and what to download.
155 </p>
156
157 <p>
158 You should download the indicated file(s) into
159 <path>/usr/portage/distfiles</path>. Once there, you can rerun the emerge
160 command, at which point the JRE/JDK will be begin to install.
161 </p>
162
163 </body>
164 </section>
165 </chapter>
166
167 <chapter>
168 <title>Configuring your virtual machine</title>
169 <section>
170 <title>Overview</title>
171 <body>
172
173 <p>
174 Gentoo has the ability to have multiple JDKs and JREs installed without causing
175 conflicts.
176 </p>
177
178 <p>
179 Using the <c>java-config</c> tool, you can set the system-wide default
180 (provided you have root access). Users can also use <c>java-config</c> to set
181 up their own personal default.
182 </p>
183
184 <note>
185 You can also use <e>eselect</e> to change the system and user vm. See
186 <c>eselect java-vm help</c>.
187 </note>
188
189 </body>
190 </section>
191 <section>
192 <title>Setting a default virtual machine</title>
193 <body>
194
195 <p>
196 Running the command <c>java-config --list-available-vms</c> will give you a
197 list of all JREs and JDKs installed on your system. Here is an example of
198 output:
199 </p>
200
201 <pre caption="Listing available VMs">
202 # <i>java-config --list-available-vms</i>
203 The following VMs are available for generation-2:
204 1) IcedTea6-bin 1.4.1 [icedtea6-bin]
205 2) Sun JDK 1.5.0.20 [sun-jdk-1.5] <comment>(Build Only)</comment>
206 *) Sun JDK 1.6.0.16 [sun-jdk-1.6]
207 </pre>
208
209 <note>
210 VMs marked as Build Only may contain security vulnerabilities and/or be EOL.
211 Gentoo recommends not setting these VMs as either your system or user VM.
212 Please see <uri link="java.xml#build-only">Build Only VM</uri> for more
213 information.
214 </note>
215
216 <p>
217 The <e>*</e> indicates this is the current active vm (system-vm or user-vm when
218 set). The name in the brackets (<e>[]</e>) is the handle or ID for that
219 particular VM. You use the handle or the number to <c>java-config
220 --set-system-vm</c>. Here is an example of how to set the system VM.
221 </p>
222
223 <pre caption="Setting the System VM">
224 <comment>(By handle (preferred))</comment>
225 # <i>java-config --set-system-vm sun-jdk-1.6</i>
226 Now using sun-jdk-1.6 as your generation-2 system JVM
227 <comment>(By number)</comment>
228 # <i>java-config --set-system-vm 3</i>
229 Now using sun-jdk-1.6 as your generation-2 system JVM
230 </pre>
231
232 <p>
233 As a regular user, you can use <c>java-config --set-user-vm</c>.
234 </p>
235
236 <note>
237 You no longer have to <c>source</c> the profile for updates to the user/system
238 VM take place.
239 </note>
240
241 </body>
242 </section>
243 <section id="build-only">
244 <title>Build Only VM</title>
245 <body>
246
247 <p>
248 Some virtual machines are flagged as build-only due to being EOL and/or
249 containing security vulnerabilities. These virtual machines will not
250 automatically be used by Gentoo for the running of applications using Gentoo
251 launchers but will still be available for use by Gentoo's build environment as
252 some packages may require them for building. The setting of these virtual
253 machines as either your system or user VM is strongly discouraged as these VMs
254 will then be used when running the <path>/usr/bin/{java,javac,..}</path>
255 executables and will also be used by any packages not using Gentoo's launcher
256 scripts.
257 </p>
258
259 </body>
260 </section>
261 <section id="preferred-vm">
262 <title>Preferred Build VM</title>
263 <body>
264
265 <p>
266 While merging Java packages, the VM used for building can sometimes be different
267 from the one currently set as the system VM.
268 </p>
269
270 <p>
271 This merge time VM switching is needed when, for example, your system-vm is
272 set to a 1.6 VM and the package you are merging requires a 1.5 VM. While merging
273 it will select and use a 1.5 VM, leaving your system-vm choice intact.
274 </p>
275
276 <p>
277 To define which VM is selected when a switch is needed, we have created a list of <e>default/supported
278 VMs</e> per arch. You can find them in
279 <path>/usr/share/java-config-2/config/jdk-defaults.conf</path>.
280 </p>
281
282 <p>
283 Of course, Gentoo is all about choice, so you can override these defaults (and even your
284 selected system VM) in
285 <path>/etc/java-config-2/build/jdk.conf</path> and have complete control over
286 which VM will get used for merging. Some examples:
287 </p>
288
289 <pre caption="Example /etc/java-config-2/build/jdk.conf">
290 <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>
291 *=sun-jdk
292 </pre>
293
294 <pre caption="Example /etc/java-config-2/build/jdk.conf">
295 <comment>(Always use sun-jdk-1.5 wherever possible, except for when a 1.4 or 1.3 VM is explicitly required)</comment>
296 *=sun-jdk-1.5
297 </pre>
298
299 <pre caption="Example /etc/java-config-2/build/jdk.conf">
300 <comment># For 1.3 I prefer sun-jdk 1.4 but when it is not available, use ibm-jdk-bin,
301 # For 1.5, use sun-jdk </comment>
302 1.3=sun-jdk-1.4 ibm-jdk-bin
303 1.5=sun-jdk
304 </pre>
305
306 <warn>
307 You do not <e>have</e> to edit this file. If you change these options to use a
308 unsupported VM, things could possibly break. Because of the wide variety of available
309 VMs, we do not have the resources to test and verify every package works on all of them.
310 Bugs reported with a unsupported VM won't be prioritized as much as bugs present within
311 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-X.Y 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</ti>
379 <ti>dev-java/eclipse-ecj</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 Plugins</title>
472 <section>
473 <title>Installing a plugin</title>
474 <body>
475
476 <p>
477 You can install a Java plugin 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 plugins 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 plugins, though
489 only one will be used by your browser. You can check the list of available
490 plugins by running:
491 </p>
492
493 <pre caption="Viewing available plugins">
494 # <i>eselect java-nsplugin list</i>
495 [1] sun-jre-bin-1.6
496 [2] icedtea6-bin
497 </pre>
498
499 <p>
500 In this example, <c>sun-jre-bin</c> is selected for the browser plugin.
501 </p>
502
503 <pre caption="Selecting a plugin">
504 # <i>eselect java-nsplugin set sun-jre-bin-1.6</i>
505 </pre>
506
507 <p>
508 Verify that the correct plugin was selected:
509 </p>
510
511 <pre caption="Verifying the correct plugin">
512 # <i>eselect java-nsplugin list</i>
513 [1] sun-jre-bin-1.6 current
514 [2] icedtea6-bin
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 plugin</uri>. Additionally, if you are using a Mozilla-based browser, you can
521 verify your Java plugin by typing <c>about:plugins</c> into the address bar.
522 </p>
523
524 </body>
525 </section>
526 <section>
527 <title>Plugins 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
532 AMD64), you can use 64-bit and 32-bit Java plugins. Unless you have a pressing
533 need to run 32-bit Java applications, we recommend using native 64-bit plugins
534 on 64-bit web browsers.
535 </p>
536
537 <p>
538 There are several native 64-bit browser plugins available. The default JDK/JRE
539 pair, <c>sun-jdk</c> and <c>sun-jre-bin</c>, both include browser plugins. Just
540 emerge one of them with the <c>nsplugin</c> USE flag enabled.
541 </p>
542
543 <pre caption="Installing a 64-bit plugin">
544 # <i>echo "dev-java/sun-jre-bin nsplugin" >> /etc/portage/package.use</i>
545 # <i>emerge sun-jre-bin</i>
546 </pre>
547
548 <p>
549 To use a 32-bit plugin on a 32-bit browser, you will need to emerge
550 <c>emul-linux-x86-java</c> with the <c>nsplugin</c> USE flag enabled.
551 </p>
552
553 <pre caption="Installing a 32-bit plugin">
554 # <i>echo "app-emulation/emul-linux-x86-java nsplugin" >> /etc/portage/package.use</i>
555 # <i>emerge emul-linux-x86-java</i>
556 </pre>
557
558 <p>
559 Next, check which plugins are available:
560 </p>
561
562 <pre caption="Viewing available plugins">
563 # <i>eselect java-nsplugin list</i>
564 Available 32-bit Java browser plugins
565 [1] emul-linux-x86-java-1.5
566 [2] emul-linux-x86-java-1.6
567 Available 64-bit Java browser plugins
568 [1] icedtea6-bin
569 [2] sun-jre-bin-1.6
570 </pre>
571
572 <p>
573 Now select the right plugin for your browsers:
574 </p>
575
576 <pre caption="Selecting plugins">
577 <comment>(Choose the plugins for 32-bit and 64-bit browsers)</comment>
578 # <i>eselect java-nsplugin set 32bit emul-linux-x86-java-1.6</i>
579 # <i>eselect java-nsplugin set 64bit sun-jre-bin-1.6</i>
580 </pre>
581
582 <p>
583 Verify the correct plugin was selected:
584 </p>
585
586 <pre caption="Verifying the correct plugin">
587 # <i>eselect java-nsplugin list</i>
588 Available 32-bit Java browser plugins
589 [1] emul-linux-x86-java-1.5
590 [2] emul-linux-x86-java-1.6 current
591 Available 64-bit Java browser plugins
592 [1] icedtea6-bin
593 [2] sun-jre-bin-1.6 current
594 </pre>
595
596 </body>
597 </section>
598 </chapter>
599
600 <chapter>
601 <title>USE flags for use with Java</title>
602 <section>
603 <title>Setting USE flags</title>
604 <body>
605
606 <p>
607 For more information regarding USE flags, refer to the <uri
608 link="/doc/en/handbook/handbook-x86.xml?part=2&amp;chap=2">USE flags</uri>
609 chapter from the Gentoo Handbook.
610 </p>
611
612 </body>
613 </section>
614 <section>
615 <title>The flags</title>
616 <body>
617
618 <ul>
619 <li>The <b>java</b> flag adds support for Java in a variety of programs</li>
620 <li>
621 The <b>nsplugin</b> flag adds support for Mozilla-like browsers (including
622 Firefox). You will need this for viewing Java applets in your Mozilla-like
623 browser.
624 </li>
625 <li>
626 The <b>source</b> flag installs a zip of the source code of a package.
627 This is traditionally used for IDEs to 'attach' source to the libraries you
628 are using.
629 </li>
630 <li>The <b>jce</b> flag adds support for the Java Cryptography Engine</li>
631 <li>
632 For Java packages, the <b>doc</b> flag will build API documentation using
633 javadoc.
634 </li>
635 </ul>
636
637 </body>
638 </section>
639 </chapter>
640
641 <chapter>
642 <title>Additional resources</title>
643 <section>
644 <title>Off-line resources</title>
645 <body>
646
647 <ul>
648 <li>java-config man page</li>
649 <li><c>java-config --help</c></li>
650 </ul>
651
652 </body>
653 </section>
654 <section>
655 <title>Online resources</title>
656 <body>
657
658 <ul>
659 <li>
660 The <uri link="http://www.gentoo.org/proj/en/java/">Java Project
661 Page</uri>
662 </li>
663 <li>
664 The <uri
665 link="http://news.gmane.org/gmane.linux.gentoo.java">gentoo-java</uri>,
666 <uri
667 link="http://news.gmane.org/gmane.linux.gentoo.user">gentoo-user</uri>, and
668 <uri
669 link="http://news.gmane.org/gmane.linux.gentoo.devel">gentoo-dev</uri>
670 mailing list archives
671 </li>
672 <li>
673 <uri link="irc://irc.gentoo.org/gentoo">#gentoo</uri> and <uri
674 link="irc://irc.gentoo.org/gentoo-java">#gentoo-java</uri> on IRC
675 </li>
676 <li>
677 <uri
678 link="http://en.wikipedia.org/wiki/Java_programming_language">Wikipedia's
679 entry for Java</uri>
680 </li>
681 <li>
682 If you have suggestions or questions regarding this document, please email
683 the Gentoo Java team: <mail>java@gentoo.org</mail>
684 </li>
685 </ul>
686
687 </body>
688 </section>
689 </chapter>
690 </guide>

  ViewVC Help
Powered by ViewVC 1.1.20