Attachment 90038 Details for Bug 137760 – edited java.xml

edited java.xml

java.xml (text/plain), 12.80 KB, created by nm (RETIRED) on 2006-06-24 09:06:10 UTC

(hide)

Description:

Filename:

MIME Type:

Creator: nm (RETIRED)

Created: 2006-06-24 09:06:10 UTC

Size: 12.80 KB

patch

obsolete

><?xml version="1.0" encoding="UTF-8"?>
>
><!DOCTYPE guide SYSTEM "/dtd/guide.dtd">
>
><guide link="/doc/en/java.xml">
><title>Gentoo Java Guide</title>
>
><author title="Author">
> <mail link="karltk@gentoo.org">Karl Trygve Kalleberg</mail>
></author>
><author title="Author">
> <mail link="nichoj@gentoo.org">Joshua Nichols</mail>
></author>
><author title="Editor">
> <mail link="nightmorph@gentoo.org">Joshua Saddler</mail>
></author>
>
><abstract>
>This guide will introduce you to Java and explain how to use Java with Gentoo
>Linux.
></abstract>
>
>
>
><license/>
>
><version>0.4</version>
><date>2006-06-24</date>
>
><chapter>
><title>What is Java?</title>
><section>
><title>Overview</title>
><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. 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.  is a JRE for
>each supported OS that runs natively on the OS.
></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.
></p>
>
></body>
></section>
></chapter>
>
><chapter>
><title>Installing a JRE/JDK</title>
><section>
><title>The choices</title>
><body>
>
><p>
>Gentoo provides numerous JREs and JDKs. Among the current alternatives, we
>have:
></p>
>
><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>
>
>
>
><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 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 inform you how to download the
>appropriate files.
></p>
>
></body>
></section>
><section>
><title>Installing a JRE/JDKs</title>
><body>
>
><p>
>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>
>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 there, you can rerun the emerge
>command, at which point the JRE/JDK will be begin to install.
></p>
>
></body>
></section>
></chapter>
>
><chapter>
><title>Configuring your JRE/JDK</title>
><section>
><title>Overview</title>
><body>
>
><p>
>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
>(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 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>
>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 <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">
><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 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>
>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>
>
><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>
><section>
><title>Setting a default CLASSPATH</title>
><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>
>
><chapter>
><title>USE flags for use with Java</title>
><section>
><title>Setting USE flags</title>
><body>
>
><p>
>For more information regarding USE flags, refer to the <uri
>link="/doc/en/handbook/handbook-x86.xml?part=2&amp;chap=2">USE flags</uri>
>chapter from the Gentoo Handbook.
></p>
>
></body>
></section>
><section>
><title>The flags</title>
><body>
>
><ul>
>  <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>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 typicall used to provide your IDE with the source code for the
>    package.
>  </li>
></ul>
>
></body>
></section>
></chapter>
>
><chapter>
><title>Additional resources</title>
><section>
><title>Off-line resources</title>
><body>
>
><ul>
>  <li>java-config man page</li>
>  <li><c>java-config --help</c></li>
></ul>
>
></body>
></section>
><section>
><title>Online resources</title>
><body>
>
><ul>
>  <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.java">gentoo-java</uri>,
>    <uri
>    link="http://news.gmane.org/gmane.linux.gentoo.user">gentoo-user</uri>,
>    <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>
>  <li>
>    <uri
>    link="http://en.wikipedia.org/wiki/Java_programming_language">Wikipedia's
>    entry for Java</uri>
>  </li>
></ul>
>
></body>
></section>
></chapter>
></guide>
>

Actions: View

Attachments on bug 137760: 90038 | 90039