nightmorph 06/06/24 18:28:06 Modified: java.xml Log: Overhauled, updated java guide for bug 137760. thanks to nichoj for putting in all the time and energy on the update.
Revision Changes Path 1.23 xml/htdocs/doc/en/java.xml file : http://www.gentoo.org/cgi-bin/viewcvs.cgi/xml/htdocs/doc/en/java.xml?rev=1.23&content-type=text/x-cvsweb-markup&cvsroot=gentoo plain: http://www.gentoo.org/cgi-bin/viewcvs.cgi/xml/htdocs/doc/en/java.xml?rev=1.23&content-type=text/plain&cvsroot=gentoo diff : http://www.gentoo.org/cgi-bin/viewcvs.cgi/xml/htdocs/doc/en/java.xml.diff?r1=1.22&r2=1.23&cvsroot=gentoo Index: java.xml =================================================================== RCS file: /var/cvsroot/gentoo/xml/htdocs/doc/en/java.xml,v retrieving revision 1.22 retrieving revision 1.23 diff -u -r1.22 -r1.23 --- java.xml 6 Mar 2006 17:46:45 -0000 1.22 +++ java.xml 24 Jun 2006 18:28:06 -0000 1.23 @@ -1,29 +1,31 @@ <?xml version="1.0" encoding="UTF-8"?> -<!-- $Header: /var/cvsroot/gentoo/xml/htdocs/doc/en/java.xml,v 1.22 2006/03/06 17:46:45 neysx Exp $ --> +<!-- $Header: /var/cvsroot/gentoo/xml/htdocs/doc/en/java.xml,v 1.23 2006/06/24 18:28:06 nightmorph Exp $ --> <!DOCTYPE guide SYSTEM "/dtd/guide.dtd"> <guide link="/doc/en/java.xml"> <title>Gentoo Java Guide</title> -<author title="Author and Editor"> +<author title="Author"> <mail link="[EMAIL PROTECTED]">Karl Trygve Kalleberg</mail> </author> -<author title="Editor"> - <mail link="[EMAIL PROTECTED]">Sven Vermeulen</mail> +<author title="Author"> + <mail link="[EMAIL PROTECTED]">Joshua Nichols</mail> </author> <author title="Editor"> - <mail link="[EMAIL PROTECTED]">Marcelo Góes</mail> + <mail link="[EMAIL PROTECTED]">Joshua Saddler</mail> </author> <abstract> -This guide will introduce users and developers to Java and explain how to use -Java with Gentoo Linux. +This guide will introduce you to Java and explain how to use Java with Gentoo +Linux. </abstract> +<!-- The content of this document is licensed under the CC-BY-SA license --> +<!-- See http://creativecommons.org/licenses/by-sa/2.5 --> <license/> -<version>0.3</version> -<date>2005-12-12</date> +<version>0.4</version> +<date>2006-06-24</date> <chapter> <title>What is Java?</title> @@ -32,21 +34,22 @@ <body> <p> -Java is a programming language developed by engineers of Sun Microsystems. -The language is object-oriented and designed to run on multiple platforms -without the need of recompiling code for each platform. Although Java can -be compiled as a native program, much of Java's popularity can be attributed -to its portability, along with other features such as garbage collection. -The ability to compile once and run in various platforms is achieved through -the use of just-in-time compilers (JIT), which compile Java bytecodes into -native code when a given program is run. +Java is a programming language developed by engineers of Sun Microsystems. The +language is object-oriented and designed to run on multiple platforms without +the need of recompiling code for each platform. Although Java can be compiled +as a native program, much of Java's popularity can be attributed to its +portability, along with other features such as garbage collection. To make +platform independence possible the Java compiler compiles the Java code to an +intermediate representation called "Java bytecode" that runs on a JRE (Java +Runtime Environment) and not directly on the operating system. </p> <p> -In order to run Java bytecodes, one needs to have a JRE (Java Runtime Environment) -installed. A JRE provides core libraries, a platform dependent Java Virtual Machine, -plug-ins for browsers, among other things. A JDK (Java Development Kit) adds -programming tools, such as a bytecode compiler and a debugger. +In order to run Java bytecode, one needs to have a JRE (Java Runtime +Environment) installed. A JRE provides core libraries, a platform dependent +Java Virtual Machine, plug-ins for browsers, among other things. A JDK (Java +Development Kit) adds programming tools, such as a bytecode compiler and a +debugger. </p> </body> @@ -60,55 +63,98 @@ <body> <p> -Gentoo provides numerous JREs and JDKs. Among the current alternatives, we have: +Gentoo provides numerous JREs and JDKs. Among the current alternatives, we +have: </p> -<ul> - <li>blackdown-jre and blackdown-jdk, the Blackdown Java Kit</li> - <li>sun-jre-bin and sun-jdk, Sun's Java Kit </li> - <li>ibm-jre-bin and ibm-jdk-bin, the IBM Java Kit</li> - <li>compaq-jre and compaq-jdk, the Compaq Java Kit for Alpha/Linux/GNU</li> - <li>jrockit-jdk-bin, BEA WebLogic's J2SE Development Kit</li> -</ul> - -<p> -The default is the Blackdown JRE/JDK -pair, as it is freely ("free as in beer") available without any registration -fuss. +<table> +<tr> + <th>Vendor</th> + <th>JDK</th> + <th>JRE</th> +</tr> +<tr> + <ti>The Blackdown Java Kit</ti> + <ti>dev-java/backdown-jdk</ti> + <ti>dev-java/blackdown-jre</ti> +</tr> +<tr> + <ti>Sun's Java Kit</ti> + <ti>dev-java/sun-jdk</ti> + <ti>dev-java/sun-jre-bin</ti> +</tr> +<tr> + <ti>The IBM Java Kit</ti> + <ti>dev-java/ibm-jdk-bin</ti> + <ti>dev-java/ibm-jre-bin</ti> +</tr> +<tr> + <ti>The Compaq Java Kit for Alpha/Linux/GNU</ti> + <ti>dev-java/compaq-jdk</ti> + <ti>dev-java/compaq-jre</ti> +</tr> +<tr> + <ti>BEA WebLogic's J2SE Development Kit</ti> + <ti>dev-java/jrockit-jdk-bin</ti> +</tr> +</table> + +<!-- +TODO: list free implmentations? +note about not drop-in replacemenets +kaffe/sablevm/gcj/jamvm +--> + +<p> +The default is Blackdown for both the JRE and the JDK, as it is freely ("free +as in beer") available without any registration fuss. </p> <p> -Both the Sun JRE/JDK and the IBM JRE/JDK are generally faster, but getting them -is a bit more work, as you are required to read and accept their license before -downloading (IBM additionally requires you to register). +Both the Sun and the IBM are generally faster, but getting them is a bit more +hassle, as you are required to read and accept their license before downloading +(IBM additionally requires you to register). </p> <p> -Our ebuilds for the Sun and IBM JRE/JDKs will notify you of where to go to -download them. +Our ebuilds for the Sun and IBM JRE/JDKs will inform you how to download the +appropriate files. </p> </body> </section> <section> -<title>Installing the Sun/IBM JRE/JDKs</title> +<title>Installing a JRE/JDKs</title> <body> <p> -If you run <c>emerge =sun-jdk-1.4.2.06</c> or <c>=ibm-jdk-bin-1.4.2</c>, you will -be notified that you are required to download the actual tarballs yourself. This -has to do with license restrictions for the Sun JRE/JDK (online click-wrap -license) and registration issues with the IBM JRE/JDK. +To install your profile's default JDK, you can run <c>emerge virtual/jdk</c>. +Or to install your profile's default JRE, you can <c>emerge virtual/jre</c>. </p> <note> -ibm-jdk-bin is currently masked, you may have to unmask it to use it. +A JDK also includes a JRE, so if you install a JDK you shouldn't have to also +have to install a JRE. </note> +</body> +</section> +<section> +<title>Installing the Sun/IBM JRE/JDKs</title> +<body> + +<p> +If you run <c>emerge dev-java/sun-jdk</c> or <c>emerge +dev-java/ibm-jdk-bin</c>, you will be notified that you are required to +download the actual files yourself. This has to do with license restrictions +for the Sun JRE/JDK (online click-wrap license) and registration issues with +the IBM JRE/JDK. +</p> + <p> You should download the indicated file(s) into -<path>/usr/portage/distfiles</path>. Once that is done, you can rerun the emerge -command, then the JRE/JDK will be installed properly into <path>/opt</path>. +<path>/usr/portage/distfiles</path>. Once there, you can rerun the emerge +command, at which point the JRE/JDK will be begin to install. </p> </body> @@ -122,75 +168,280 @@ <body> <p> -Gentoo has the ability to have multiple JDKs and JREs installed without them -conflicting. +Gentoo has the ability to have multiple JDKs and JREs installed without causing +conflicts. </p> <p> -Using the <c>java-config</c> tool, you can set the system-wide default if you -have root access. Users can also use <c>java-config</c> to set up their own -personal default, that is different from the system-wide default. +Using the <c>java-config</c> tool, you can set the system-wide default +(provided you have root access). Users can also use <c>java-config</c> to set +up their own personal default. </p> +<note> +You can also use <e>eselect</e> to change the system and user vm. See +<c>eselect java help</c>. +</note> + </body> </section> - <section> <title>Setting a default JRE/JDK</title> <body> <p> -Running the command <c>java-config --list-available-vms</c> will give you a list -of all available JREs and JDKs on your system. Here is an example of output: +Running the command <c>java-config --list-available-vms</c> will give you a +list of all JREs and JDKs installed on your system. Here is an example of +output: </p> <pre caption="Listing available VMs"> # <i>java-config --list-available-vms</i> -[blackdown-jdk-1.3.1] Blackdown JDK 1.3.1 (/etc/env.d/java/20blackdown-jdk-1.3.1) -[blackdown-jre-1.3.1] Blackdown JRE 1.3.1 (/etc/env.d/java/20blackdown-jre-1.3.1) -[ibm-jdk-1.3.0] IBM JDK 1.3.0 (/etc/env.d/java/20ibm-jdk-1.3.0) -[ibm-jdk-1.3.1] IBM JDK 1.3.1 (/etc/env.d/java/20ibm-jdk-1.3.1) -[ibm-jre-1.3.1] IBM JRE 1.3.1 (/etc/env.d/java/20ibm-jre-1.3.1) -[sun-jdk-1.4.0] Sun JDK 1.4.0 (/etc/env.d/java/20sun-jdk-1.4.0) +1) Blackdown JDK 1.3.1 [blackdown-jdk-1.3] (/etc/env.d/java/20blackdown-jdk-1.3) +2) Blackdown JDK 1.4.2.02 [blackdown-jdk-1.4] (/etc/env.d/java/20blackdown-jdk-1.4) +3) Blackdown JRE 1.4.2.02 [blackdown-jre-1.4] (/etc/env.d/java/20blackdown-jre-1.4) +4) IBM JDK 1.4.2 [ibm-jdk-bin-1.4] (/etc/env.d/java/20ibm-jdk-bin-1.4) +5) IBM JRE 1.4.2 [ibm-jre-bin-1.4] (/etc/env.d/java/20ibm-jre-bin-1.4) +6) WebLogic JRockit 1.4.2.05 [jrockit-jdk-bin-1.4] (/etc/env.d/java/20jrockit-jdk-bin-1.4) +7) WebLogic JRockit 1.5.0.03 [jrockit-jdk-bin-1.5] (/etc/env.d/java/20jrockit-jdk-bin-1.5) +8) Sun JDK 1.3.1.13 [sun-jdk-1.3] (/etc/env.d/java/20sun-jdk-1.3) +9) Sun JDK 1.4.2.09 [sun-jdk-1.4] (/etc/env.d/java/20sun-jdk-1.4) +*) Sun JDK 1.5.0.04 [sun-jdk-1.5] (/etc/env.d/java/20sun-jdk-1.5) +11) Sun JRE 1.4.2.09 [sun-jre-bin-1.4] (/etc/env.d/java/20sun-jre-bin-1.4) +12) Sun JRE 1.5.0.04 [sun-jre-bin-1.5] (/etc/env.d/java/20sun-jre-bin-1.5) </pre> <p> -The name in the brackets <path>"[]"</path> is the handle or ID for that -particular VM. You use pass that ID to <c>java-config --set-system-vm</c>. Here is -an example of how to set the system VM. +The <e>*</e> indicates this is the current active vm (system-vm or user-vm when +set). The name in the brackets (<e>[]</e>) is the handle or ID for that +particular VM. You use the handle or the number to <c>java-config +--set-system-vm</c>. Here is an example of how to set the system VM. </p> <pre caption="Setting the System VM"> -# <i>java-config --set-system-vm ibm-jdk-1.3.1</i> -Now using IBM JDK 1.3.1 (/etc/env.d/java/20ibm-jdk-1.3.1) +<comment>(By handle (preferred))</comment> +# <i>java-config --set-system-vm blackdown-jdk-1.4</i> +<comment>(By number)</comment> +# <i>java-config --set-system-vm 2</i> </pre> +<p> +As a regular user, you can use <c>java-config --set-user-vm</c>. +</p> + <note> -You will have to be root to run --set-system-vm. +You no longer have to <c>source</c> the profile for updates to the user/system +VM take place. </note> +</body> +</section> +<section id="preferred-vm"> +<title>Preferred VM</title> +<body> + +<p> +While merging Java packages, the VM can and will be switched as necessary. +</p> + +<p> +Because of the wide variety of available VMs, we do not have the resources to +test and verify every package works on all of them. So to ensure that every +packages merges smoothly, we have defined a list of <e>default/supported +VMs</e> per arch. You can find them in +<path>/usr/share/java-config/config/jdk-defaults.conf</path>. When you are +merging a Java package, and it detects one of the VM in that file is installed, +it will automatically use that VM, instead of the system-vm. +</p> + <p> -Once you have issued <c>java-config --set-system-vm</c> with a particular VM -ID, you will need to regenerate your <path>/etc/profile.env</path>. You can do -it like this: +The merge time VM switching is also needed when, for example, your system-vm is +set a 1.4 VM and the package you are merging requires a 1.5 VM. While merging +it will use the preferred 1.5 VM, leaving your system-vm choice intact. </p> -<pre caption="Regenerating /etc/profile.env" > -# <i>env-update</i> +<p> +Of course, Gentoo is all about choice, so you can override these defaults in +<path>/etc/java-config-2/build/jdk.conf</path> and have complete control over +which VM will get used. Some examples: +</p> + +<pre caption="Example /etc/java-config-2/build/jdk.conf"> +<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> +*=sun-jdk </pre> +<pre caption="Example /etc/java-config-2/build/jdk.conf"> +<comment>(Always use sun-jdk-1.5 wherever possible, except for when a 1.4 or 1.3 VM is explicitly required)</comment> +*=sun-jdk-1.5 +</pre> + +<pre caption="Example /etc/java-config-2/build/jdk.conf"> +<comment># For 1.3 I prefer sun-jdk 1.4 but when it is not available, use ibm-jdk-bin, +# For 1.4, use blackdown-jdk, and for 1.5, use sun-jdk </comment> +1.3=sun-jdk-1.4 ibm-jdk-bin +1.4=blackdown-jdk +1.5=sun-jdk +</pre> + +<warn> +You do not have to edit this file. If you change these options to use a +unsupported VM, things could possibly break. Bugs reported with a unsupported +VM will a lower priority if they aren't present with supported VMs. +</warn> + +</body> +</section> +</chapter> + +<chapter> +<title>Compilers</title> +<section> +<body> + <p> -After this, you will either want to relogin, or resource -<path>/etc/profile</path> into your environment. +The standard Java compiler used for building is javac, which comes with each +JDK. In addition to configuring the VM used at build time, it is also possible +configure which compiler is used. Essentially, you define a list your +preference for which compiler to use in +<path>/etc/java-config-2/build/compilers.conf</path>. </p> +<pre caption="/etc/java-config-2/build/compilers.conf"> +# If the ebuild supports it +# it will check the COMPILERS var front to back and +# use the first compiler that is installed + +COMPILERS="ecj-3.1 jikes javac" +</pre> + <p> -As a regular user, you can use <c>java-config --set-user-vm</c>, which will -create <path>~/.gentoo/java-env</path> with all required env vars. You would -normally source this from your shell's startup script (generally -<path>~/.bashrc</path>). +Some compilers don't support all possible -target and -source arguments. +Therefore, each compiler in the list is checked to see if it can support the +desired -source/-target. javac will work in all cases, so if no other suitable +compiler is found, it will be used instead. </p> +<p> +More details about each compiler are provided below: +</p> + +<table> +<tr> + <th>Name</th> + <th>Handle</th> + <th>Package</th> + <th>Description</th> +</tr> +<tr> + <ti>javac</ti> + <ti>javac</ti> + <ti>N/A</ti> + <ti> + This is the default compiler that will be used, and comes with each JDK. + </ti> +</tr> +<tr> + <ti>jikes</ti> + <ti>jikes</ti> + <ti>dev-java/jikes</ti> + <ti> + Jikes was originally developed by IBM. Anecdotally, it is generally quicker + than javac. Note however, that it is more pedantic, and will fail under a + few circumstances where javac has no issue. It also does not support Java + 1.5 syntax yet. + </ti> +</tr> +<tr> + <ti>Eclipse Compiler for Java</ti> + <ti>ecj-3.1</ti> + <ti>=dev-java/eclipse-ecj-3.1*</ti> + <ti> + ECJ is the compiler used by the Eclipse software development kit. It is + very full featured, and is pretty fast. It does support Java 1.5 syntax. + </ti> +</tr> +</table> + +</body> +</section> +</chapter> + +<chapter> +<title>Setting a default CLASSPATH</title> +<section> +<body> + +<warn> +The options explained in this section should be considered deprecated and will +be most likely be removed in the future. We strongly recommend against using +these, because your Java projects or application should ideally manage their +own classpaths. If you choose to specify a default CLASSPATH, some applications +may behave unexpectedly, because classes they weren't expecting would be on the +classpath. +</warn> + +<p> +<c>java-config</c> can also be used to set a system-wide default CLASSPATH, as +well a user-specific default CLASSPATH. +</p> + +<p> +First, you will want to list available Java libraries installed on your system +that might want to be put in your CLASSPATH. Here is an example of output: +</p> + +<pre caption="Listing classes"> +# <i>java-config --list-available-packages</i> +[xerces-2] The next generation of high performance, fully compliant XML parsers in the Apache Xerces family (/usr/share/xerces-2/package.env) +[junit] Simple framework to write repeatable tests (/usr/share/junit/package.env) +[bsh] BeanShell: A small embeddable Java source interpreter (/usr/share/bsh/package.env) +[bcel] The Byte Code Engineering Library: analyze, create, manipulate Java class files (/usr/share/bcel/package.env) +[log4j] A low-overhead robust logging package for Java (/usr/share/log4j/package.env) +... +</pre> + +<p> +Again, the names in brackets (<e>[]</e>) are the IDs that you have to pass to +<c>java-config --set-system-classpath</c>. Here is an example: +</p> + +<pre caption="Setting classpaths"> +# <i>java-config --set-system-classpath log4j,xerces-2</i> +</pre> + +<note> +The current directory (<path>.</path>) will not be part of the system +classpath, as that should be added in your system's login profile. +</note> + +<p> +You will have to update your environment by relogging in or sourcing +<path>/etc/profile</path>. +</p> + +<p> +For users, <c>java-config --set-user-classpath</c> will create +<path>~/.gentoo/java-env-classpath</path>, which you should then source from +your shell's profile. +</p> + +<pre caption="Sourcing user specific classpath"> +<i>if [[ -f "${HOME}/.gentoo/java-env-classpath" ]]; then + source ${HOME}/.gentoo/java-env-classpath +fi</i> +</pre> + +<p> +If you really want a system wide or user default classpath you can add +something like like the following to your shell's profile. But we would advise +against it. +</p> + +<pre caption="Setting classpath"> +# <i>export CLASSPATH="${CLASSPATH}:$(java-config --classpath log4j,xerces-2)"</i> +</pre> + </body> </section> </chapter> @@ -214,12 +465,20 @@ <body> <ul> - <li>The <b>java</b> flag adds support for Java in a variety of programs.</li> + <li>The <b>java</b> flag adds support for Java in a variety of programs</li> + <li> + The <b>nsplugin</b> flag adds support for Mozilla-like browsers (including + Firefox).You will need this for viewing Java applets in your Mozilla-like + browser. + </li> <li> - The <b>nsplugin</b> flag adds a symlink to the javaplugin for - Mozilla-like browsers (including Firefox) if you are using, for example, - Blackdown's Java kit, IBM Java Kit or Sun's Java Kit. You will need this - for viewing Java applets in your Mozilla-like browser. + The <b>doc</b> flag will typically install API documentation, as generated + by javadoc. + </li> + <li> + The <b>source</b> flag will install a zip of the package's source code. + This is typically used to provide your IDE with the source code for the + package. </li> </ul> @@ -236,7 +495,6 @@ <ul> <li>java-config man page</li> <li><c>java-config --help</c></li> - <li>The <path>/usr/bin/java-config</path> script itself</li> </ul> </body> @@ -246,13 +504,17 @@ <body> <ul> - <li>The <uri link="/proj/en/java/">Gentoo Java Project Page</uri></li> + <li> + The <uri link="http://www.gentoo.org/proj/en/java/";>Java Project + Page</uri> + </li> <li> The <uri - link="http://news.gmane.org/gmane.linux.gentoo.devel";>gentoo-dev</uri>, - <uri link="http://news.gmane.org/gmane.linux.gentoo.user";>gentoo-user - </uri> and <uri - link="http://news.gmane.org/gmane.linux.gentoo.java";>gentoo-java</uri> + link="http://news.gmane.org/gmane.linux.gentoo.java";>gentoo-java</uri>, + <uri + link="http://news.gmane.org/gmane.linux.gentoo.user";>gentoo-user</uri>, and + <uri + link="http://news.gmane.org/gmane.linux.gentoo.devel";>gentoo-dev</uri> mailing list archives </li> <li>#gentoo and #gentoo-java on irc.freenode.net</li> -- [email protected] mailing list
