doc/en/java.xml

<?xml version='1.0' encoding="UTF-8"?>
<?xml-stylesheet href="/xsl/guide.xsl" type="text/xsl"?>

<guide link = "/doc/en/java.xml">
        <title>Gentoo Java Guide</title>
        <author title="Author and Editor">
        <mail link="karltk@gentoo.org">Karl Trygve Kalleberg</mail>
        </author>

        <abstract>
        Users' and Developers' Guide to Java in Gentoo
        </abstract>

    <license/>

        <version>0.1.1</version>
        <date>June 25, 2002</date>

                <chapter>
                <title>Installing a JDK/JRE</title>
                        <section>
                                <title>Overview</title>
                                <body>
                                
                        <p>Gentoo provides numerous JDKs and JREs. The default is the
                        Blackdown JDK/JRE pair, as it is freely (beer) available without any
                        registration fuss.
                        </p>

                        <note>As kaffe becomes a JRE/JDK drop-in replacement, that will most
                        likely become our default.
                        </note>

                        <p>Both the Sun JDK/JRE and the IBM JDK/JRE 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).
                        </p>

                        <p>Our ebuilds for the Sun and IBM JDK/JREs will notify you of where
                        to go to download them.
                        </p>
                        
                        </body>
                </section>

                <section>
                        <title>Installing the Sun/IBM JDK/JREs</title>
                        <body>

                        <p>If you run <c>emerge sun-jdk-1.3.1</c> or <c>emerge
                        ibm-jdk-1.3.1</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 JDK/JRE (online click-wrap license) and
                        registration issues with the IBM JDK/JRE.
                        </p>

                        <note>There is also a sun-jdk-1.4.0, but not all packages
                        work nicely with Java 1.4, so you're on your own if you use the 1.4.0
                        JDK.
                        </note>

                        <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 JDK/JRE will be installed properly into
                        <path>/opt</path>.
                        </p>
                        
                        </body>
                </section>
        </chapter>

        <chapter>
                <title>Configuring your JDK/JRE</title>
                
                <section>
                        <title>Overview</title>
                        
                        <body>
                        
                        <p>Gentoo has the ability to have multiple JDKs and JREs installed
                        without them conflicting. There are a few caveats to this, as noted
                        below.
                        </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.
                        </p>
                        
                        </body>
                </section>

                <section>
                        <title>Setting a default JDK/JRE</title>
                        <body>

                        <p>Running the command <c>java-config --list-available-vms</c> will
                        give you a list of all availble JREs and JDKs on your system, thus:</p>
                        
                        <pre caption = "Listing available VMs">
[%1 ~] java-config --list-available-vms
[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)
                        </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>, thus:
                        </p>

                        <pre caption = "Setting the System VM">
[#1 ~] java-config --set-system-vm=ibm-jdk-1.3.1
Now using IBM JDK 1.3.1 (/etc/env.d/java/20ibm-jdk-1.3.1)
                        </pre>

                        <note>You will have to be root to run --set-system-vm
                        </note>

                        <p>Once you have issued <c>java-config --set-system-vm</c> with a
                        particular VM ID, you will need to regenerate your /etc/profile.env,
                        thus:
                        </p>
                        
                        <pre caption = "Regenerating /etc/profile.env" >
[#1 ~] env-update
                        </pre>

                        <p>After this, you will either want to relogin, or resource
                        <path>/etc/profile</path> into your environment.
                        </p>

                        <p>As a regular user, you can use <c>java-config --set-user-vm</c>,
                        which will create <path>$HOME/.gentoo/java-env</path> with all
                        required env vars. You would normally source this from your shell's
                        startup script (<path>$HOME/.zshenv</path> in my case).</p>
                        
                        </body>
                </section>

                <section>
                        <title>Setting a default CLASSPATH</title>
                        <body>

                        <p><c>java-config</c> can also be used to set a system-wide default
                        CLASSPATH, and of course a user-specific default CLASSPATH.
                        </p>

                        <p>First you want to list available java libraries that might be
                        interesting to put in your CLASSPATH, thus:
                        </p>
                        
                        <pre caption = "Listing classes">
[%1 ~] java-config --list-available-packages
[ant] No description (/usr/share/ant/classpath.env)
[java-gnome] No description (/usr/share/java-gnome/classpath.env)
[java-gtk] No description (/usr/share/java-gtk/classpath.env)
[log4j] "" (/usr/share/log4j/package.env)
                        </pre>

                        <note>None of these packages have a proper description. That is
                        something that will be implemented in the not-so-distant
                        future.
                        </note>

                        <p>Again, the name in brackets <path>"[]"</path> are the IDs that you
                        have to pass to <c>java-config --set-system-classpath</c>, thus:
                        </p>

                        <pre caption = "Setting classpaths">
java-config --set-system-classpath=log4j,java-gtk,java-gnome
                        </pre>
                        
                        <note>The current directory (.) will not be part of the system classpath,
                        as that should be added in root's login profile.
                        </note>

                        <p>Again, you will want to run <c>env-update</c> to update your
                        system's environment, and you might also want to relogin or resource
                        the <path>/etc/profile</path>.
                        </p>
                        
                        <p>For users, <c>java-config --set-user-classpath</c> will create
                        <path>$HOME/.gentoo/java-env-classpath</path>, which is automatically
                        included by <path>$HOME/.gentoo/java-env</path>.
                        </p>
                        
                        </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>
                                <li>The <path>/usr/bin/java-config</path> script itself</li>
                        </ul>
                        
                        </body>
                </section>

                <section>
                        <title>Online resources</title>

                        <body>

                        <ul>
                        <li>The <uri link="http://lists.gentoo.org/pipermail/gentoo-dev/">
                                gentoo-dev </uri>, 
                                <uri link="http://lists.gentoo.org/pipermail/gentoo-user/"> gentoo-user
                                </uri> mailing list archives</li>
                        <li>#gentoo on irc.openprojects.net</li>
                        </ul>
                        
                        </body>
                </section>
        </chapter>

        <chapter>
                <title>Caveats</title>
                <section>
                        <title>General</title>

                        <body>
                        
                        <p>If you select a JRE as your default VM, you may not have a
                        <c>javac</c> command handy at all times, unless you have manually
                        installed a symlink to take care of that.
                        </p>

                        <p>Jikes will be used to compile some of the largest packages, if it
                        is available. With time, we hope to be able to compile all
                        java-dependent packages with Jikes, so some dependencies on the JDK
                        can be replaced with a dependency on the JRE.</p>

                        <p>With some versions of Portage, doing an <c>emerge --update world</c>
                        will install the JDK regardless if whether you have it
                        installed before or not. This is a known bug addressed in later
                        versions of Portage.
                        </p>
                        
                        </body>
                </section>
        </chapter>
</guide>
1	zhen	1.3	<?xml version='1.0' encoding="UTF-8"?>
2	drobbins	1.1	<?xml-stylesheet href="/xsl/guide.xsl" type="text/xsl"?>
3	zhen	1.4
4	zhen	1.2	<guide link = "/doc/en/java.xml">
5	zhen	1.4	<title>Gentoo Java Guide</title>
6			<author title="Author and Editor">
7			<mail link="karltk@gentoo.org">Karl Trygve Kalleberg</mail>
8			</author>
9
10			<abstract>
11			Users' and Developers' Guide to Java in Gentoo
12			</abstract>
13
14	swift	1.6	<license/>
15
16	zhen	1.4	<version>0.1.1</version>
17			<date>June 25, 2002</date>
18
19			<chapter>
20			<title>Installing a JDK/JRE</title>
21			<section>
22			<title>Overview</title>
23			<body>
24
25			<p>Gentoo provides numerous JDKs and JREs. The default is the
26			Blackdown JDK/JRE pair, as it is freely (beer) available without any
27			registration fuss.
28			</p>
29
30			<note>As kaffe becomes a JRE/JDK drop-in replacement, that will most
31			likely become our default.
32			</note>
33
34			<p>Both the Sun JDK/JRE and the IBM JDK/JRE are generally faster, but
35			getting them is a bit more work, as you are required to read and
36			accept their license before downloading (IBM additionally requires you
37			to register).
38			</p>
39
40			<p>Our ebuilds for the Sun and IBM JDK/JREs will notify you of where
41			to go to download them.
42			</p>
43
44			</body>
45			</section>
46
47			<section>
48			<title>Installing the Sun/IBM JDK/JREs</title>
49			<body>
50
51			<p>If you run <c>emerge sun-jdk-1.3.1</c> or <c>emerge
52			ibm-jdk-1.3.1</c>, you will be notified that you are required
53			to download the actual tarballs yourself. This has to do with license
54			restrictions for the Sun JDK/JRE (online click-wrap license) and
55			registration issues with the IBM JDK/JRE.
56			</p>
57
58			<note>There is also a sun-jdk-1.4.0, but not all packages
59			work nicely with Java 1.4, so you're on your own if you use the 1.4.0
60			JDK.
61			</note>
62
63			<p>You should download the indicated file(s) into
64			<path>/usr/portage/distfiles</path>. Once that is done, you can rerun
65			the emerge command, then the JDK/JRE will be installed properly into
66			<path>/opt</path>.
67			</p>
68
69			</body>
70			</section>
71			</chapter>
72
73			<chapter>
74			<title>Configuring your JDK/JRE</title>
75
76			<section>
77			<title>Overview</title>
78
79			<body>
80
81			<p>Gentoo has the ability to have multiple JDKs and JREs installed
82			without them conflicting. There are a few caveats to this, as noted
83			below.
84			</p>
85
86			<p>Using the <c>java-config</c> tool, you can set the system-wide
87			default if you have root access. Users can also use <c>java-config</c>
88			to set up their own personal default, that is different from the
89			system-wide default.
90			</p>
91
92			</body>
93			</section>
94
95			<section>
96			<title>Setting a default JDK/JRE</title>
97			<body>
98
99			<p>Running the command <c>java-config --list-available-vms</c> will
100			give you a list of all availble JREs and JDKs on your system, thus:</p>
101
102			<pre caption = "Listing available VMs">
103	drobbins	1.1	[%1 ~] java-config --list-available-vms
104			[blackdown-jdk-1.3.1] Blackdown JDK 1.3.1 (/etc/env.d/java/20blackdown-jdk-1.3.1)
105			[blackdown-jre-1.3.1] Blackdown JRE 1.3.1 (/etc/env.d/java/20blackdown-jre-1.3.1)
106			[ibm-jdk-1.3.0] IBM JDK 1.3.0 (/etc/env.d/java/20ibm-jdk-1.3.0)
107			[ibm-jdk-1.3.1] IBM JDK 1.3.1 (/etc/env.d/java/20ibm-jdk-1.3.1)
108			[ibm-jre-1.3.1] IBM JRE 1.3.1 (/etc/env.d/java/20ibm-jre-1.3.1)
109			[sun-jdk-1.4.0] Sun JDK 1.4.0 (/etc/env.d/java/20sun-jdk-1.4.0)
110	zhen	1.4	</pre>
111
112			<p>The name in the brackets <path>"[]"</path> is the handle or ID for
113			that particular VM. You use pass that ID to <c>java-config
114			--set-system-vm</c>, thus:
115			</p>
116
117			<pre caption = "Setting the System VM">
118	drobbins	1.1	[#1 ~] java-config --set-system-vm=ibm-jdk-1.3.1
119			Now using IBM JDK 1.3.1 (/etc/env.d/java/20ibm-jdk-1.3.1)
120	zhen	1.4	</pre>
121	drobbins	1.1
122	zhen	1.4	<note>You will have to be root to run --set-system-vm
123			</note>
124	drobbins	1.1
125	zhen	1.4	<p>Once you have issued <c>java-config --set-system-vm</c> with a
126			particular VM ID, you will need to regenerate your /etc/profile.env,
127			thus:
128			</p>
129
130			<pre caption = "Regenerating /etc/profile.env" >
131	drobbins	1.1	[#1 ~] env-update
132	zhen	1.4	</pre>
133	drobbins	1.1
134	zhen	1.4	<p>After this, you will either want to relogin, or resource
135			<path>/etc/profile</path> into your environment.
136			</p>
137
138			<p>As a regular user, you can use <c>java-config --set-user-vm</c>,
139			which will create <path>$HOME/.gentoo/java-env</path> with all
140			required env vars. You would normally source this from your shell's
141			startup script (<path>$HOME/.zshenv</path> in my case).</p>
142
143			</body>
144			</section>
145
146			<section>
147			<title>Setting a default CLASSPATH</title>
148			<body>
149
150			<p><c>java-config</c> can also be used to set a system-wide default
151			CLASSPATH, and of course a user-specific default CLASSPATH.
152			</p>
153
154			<p>First you want to list available java libraries that might be
155			interesting to put in your CLASSPATH, thus:
156			</p>
157
158			<pre caption = "Listing classes">
159	drobbins	1.1	[%1 ~] java-config --list-available-packages
160			[ant] No description (/usr/share/ant/classpath.env)
161			[java-gnome] No description (/usr/share/java-gnome/classpath.env)
162			[java-gtk] No description (/usr/share/java-gtk/classpath.env)
163			[log4j] "" (/usr/share/log4j/package.env)
164	zhen	1.4	</pre>
165
166			<note>None of these packages have a proper description. That is
167			something that will be implemented in the not-so-distant
168			future.
169			</note>
170
171			<p>Again, the name in brackets <path>"[]"</path> are the IDs that you
172			have to pass to <c>java-config --set-system-classpath</c>, thus:
173			</p>
174	drobbins	1.1
175	zhen	1.4	<pre caption = "Setting classpaths">
176	drobbins	1.1	java-config --set-system-classpath=log4j,java-gtk,java-gnome
177	zhen	1.4	</pre>
178
179			<note>The current directory (.) will not be part of the system classpath,
180			as that should be added in root's login profile.
181			</note>
182
183			<p>Again, you will want to run <c>env-update</c> to update your
184			system's environment, and you might also want to relogin or resource
185			the <path>/etc/profile</path>.
186			</p>
187
188			<p>For users, <c>java-config --set-user-classpath</c> will create
189			<path>$HOME/.gentoo/java-env-classpath</path>, which is automatically
190			included by <path>$HOME/.gentoo/java-env</path>.
191			</p>
192
193			</body>
194			</section>
195			</chapter>
196
197			<chapter>
198			<title>Additional resources</title>
199			<section>
200			<title>Off-line resources</title>
201
202			<body>
203
204			<ul>
205			<li>java-config man page</li>
206			<li><c>java-config --help</c></li>
207			<li>The <path>/usr/bin/java-config</path> script itself</li>
208			</ul>
209
210			</body>
211			</section>
212
213			<section>
214			<title>Online resources</title>
215
216			<body>
217
218			<ul>
219			<li>The <uri link="http://lists.gentoo.org/pipermail/gentoo-dev/">
220			gentoo-dev </uri>,
221			<uri link="http://lists.gentoo.org/pipermail/gentoo-user/"> gentoo-user
222			</uri> mailing list archives</li>
223			<li>#gentoo on irc.openprojects.net</li>
224			</ul>
225
226			</body>
227			</section>
228			</chapter>
229
230			<chapter>
231			<title>Caveats</title>
232			<section>
233			<title>General</title>
234
235			<body>
236
237			<p>If you select a JRE as your default VM, you may not have a
238			<c>javac</c> command handy at all times, unless you have manually
239			installed a symlink to take care of that.
240			</p>
241
242			<p>Jikes will be used to compile some of the largest packages, if it
243			is available. With time, we hope to be able to compile all
244			java-dependent packages with Jikes, so some dependencies on the JDK
245			can be replaced with a dependency on the JRE.</p>
246
247	klieber	1.5	<p>With some versions of Portage, doing an <c>emerge --update world</c>
248			will install the JDK regardless if whether you have it
249	zhen	1.4	installed before or not. This is a known bug addressed in later
250			versions of Portage.
251			</p>
252
253			</body>
254			</section>
255			</chapter>
256	drobbins	1.1	</guide>