adding docbook changes

<?xml version='1.0' encoding='utf-8'?>

<!-- -*- DocBook -*- -->

<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"

    "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [

<!-- Include entity definition file by uncommenting the following -->

<!-- <!ENTITY % versiondata SYSTEM "version.ent"> %versiondata;   -->

]>

<book lang="en">

<title>Debian Java FAQ.</title>

<bookinfo>

<authorgroup>

<author><personname>Torsten Werner</personname><email>twerner@debian.org</email></author>

<author><personname>Niels Thykier</personname><email>niels@thykier.net</email></author>

<author><personname>Javier Fernández-Sanguino Peña</personname><email>jfs@debian.org</email></author>

<author><personname>Sylvestre Ledru</personname><email>sylvestre@debian.org</email></author>

<author><personname>Shirish Agarwal</personname><email>shirishag75@gmail.com</email></author>

</authorgroup>

<releaseinfo>$Revision: 7831 $, $Date: 2013-06-05 21:17:15 +0100 $</releaseinfo>

<pubdate><!-- put date --></pubdate>

<abstract>

<para>

Answers to Frequently Asked Questions on Debian and Java (Note: some

information is not up-to-date).  Any changes/corrections to this FAQ are

appreciated.  Please send them to the Debian Bug Tracking System as described

in <xref linkend="bugs"/>.

</para>

</abstract>

</bookinfo>

<chapter id="ch1"><title>Introduction</title>

<section id="s1.1"><title>Introduction to this FAQ</title>

<para>

This FAQ was started by Javier Fernández-Sanguino who on February 1st, 2000 was

enough to send a message to the debian-java mailing list with the subject "How

about a Debian-Java-FAQ?".  Of course, since "every idea is a responsibility"

he had to do this himself looking through the three month-long archive of the

newborn mailing list.

</para>

<para>

The purpose of this FAQ is to be a place to look for all kinds of questions a

developer or user might have regarding Java as far as Debian is concerned.  It

includes license issues, development packages available, and programs related

to building a Free Software Java environment.

</para>

<para>

Thanks go to all the (many) contributors from the debian-java mailing list, who

have made this document possible.  Without their knowledge this FAQ would not

be at all possible since I only have a vague knowledge of what they're talking

about when I browse the list.

</para>

<para>

Special thanks go to Paul Reavis, whose previous Debian-JDK informational page

I used to add more information, and who made useful suggestions to this

document.  Also to Peter Moulder who revised thoroughly the FAQ and provided

many suggestions, to Juergen Kreileder, maintainer of Blackdown's debian

packages who pointed out some mistakes, and to Egon Willighagen, who has

provided quite a lot of proper patches to update its content.

</para>

<para>

This document does not address issues with other Linux distributions, or with

non-Debian-specific problems.

</para>

</section>

<section id="s1.2"><title>Location of this FAQ</title>

<para>

This FAQ is published under the Debian Documentation Project at <ulink

url="http://www.debian.org/doc/manuals/debian-java-faq/">http://www.debian.org/doc/manuals/debian-java-faq/</ulink>.

The <systemitem role="package">java-common</systemitem> (available at <ulink

url="http://packages.debian.org/java-common">http://packages.debian.org/java-common</ulink>)

provides an HTML version for offline reading.  The package version does not

provide Text and PDF versions currently (if you want them please submit a bug

'wishlist' to the package).  Also, the web version might be more up-to-date

than the package's offline version.

</para>

</section>

<section id="bugs"><title>Sending bugs on this FAQ</title>

<para>

Please note that this FAQ is still outdated but gets updated step by step.

</para>

<para>

Please file bug reports against the java-common package if you find errors or

have suggestions on how to improve this document.  However, make sure you have

read the latest online version of the english text available at <ulink

url="http://www.debian.org/doc/manuals/debian-java-faq/index.html">http://www.debian.org/doc/manuals/debian-java-faq/index.html</ulink>

before filing a bug report.  Translations, if available, and the offline

version in the java-common package might be out of date.

</para>

</section>

<section id="s1.4"><title>What is Java?</title>

<para>

Java is a programming language originally developed by James Gosling at Sun

Microsystems (which is now a subsidiary of Oracle Corporation) and released in

1995 as a core component of Sun Microsystems' Java platform.  Since May 2007,

Sun/Oracle with some partners like Red Hat provide a free implementation

released under the GNU GPL called OpenJDK.  More information can be found at

<ulink

url="http://en.wikipedia.org/wiki/Java_%28programming_language%29">Wikipedia</ulink>.

</para>

</section>

<section id="s1.5"><title>Where can I ask questions about Java on Debian?</title>

<para>

The appropriate place to ask such questions is <email>debian-java at

lists.debian.org</email>.  You can subscribe at the <ulink

url="http://lists.debian.org/debian-java/">Debian Mailing Lists</ulink> page.

</para>

</section>

<section id="moreinfo"><title>Complementary information</title>

<para>

Users might want to access some online sources to complement the information

available in this FAQ which might be, sometimes, too out of date.  The main

source of information is the <ulink url="http://wiki.debian.org/Java">Java

entry</ulink> at the Debian's wiki.

</para>

<para>

Since Ubuntu is based on Debian, some users might find it helpful to check the

tips on <ulink url="https://help.ubuntu.com/community/Java">Installing

Java</ulink> on Ubuntu's wiki.

</para>

</section>

<section id="pending"><title>Uncovered issues</title>

<para>

This FAQ does not describe some issues due to lack of time and/or information.

If you are able to help in any of these, please, provide them to the

documentation maintainer:

</para>

<itemizedlist>

<listitem>

<para>

Information on how to setup a fully working Servlet engine (Application Server)

using Apache and Tomcat or information on how to setup non-free application

servers (such as WebSphere) in Debian.

</para>

</listitem>

<listitem>

<para>

Specific information targeted for non-i386 users (PowerPC users and AMD64

users), some can be found in Ubuntu's wiki.

</para>

</listitem>

</itemizedlist>

</section>

</chapter>

<chapter id="ch2"><title>Java Development</title>

<section id="s2.1"><title>What full-fledged Java development platforms are available in Debian?</title>

<para>

If you are looking for an integrated, java virtual machine, compiler and

runtime environment Debian does provide them.  Of course that would depend on

the Debian GNU/Linux version you are using, generally speaking they would be:

</para>

<itemizedlist>

<listitem>

<para>

Sun's OpenJDK 7, available since the Debian 8.0 <emphasis>Jessie</emphasis>

release in the <emphasis>main</emphasis> section.

</para>

</listitem>

<listitem>

<para>

Oracle's OpenJDK 8, available since the Debian 9.0 <emphasis>Strech</emphasis>

release in the <emphasis>main</emphasis> section.

</para>

</listitem>

<listitem>

<para>

The combination GCJ, GIJ, and Classpath in the <emphasis>main</emphasis>

section.

</para>

</listitem>

</itemizedlist>

<para>

It is recommended to install one of the default-jdk or default-jre meta

packages which either installs OpenJDK or GCJ depending on the architecture and

Debian version.

</para>

</section>

<section id="free"><title>What free platforms are there and how can I contribute?</title>

<para>

Please help one of the Free Java implementations if you want to use Java in

Debian.  There are a lot of projects that you can choose from:

</para>

<itemizedlist>

<listitem>

<para>

openjdk: <ulink url="http://openjdk.java.net/">http://openjdk.java.net/</ulink>

</para>

</listitem>

<listitem>

<para>

Mauve <ulink

url="http://sources.redhat.com/mauve/">http://sources.redhat.com/mauve/</ulink>

is a free suite to test if these tools are 'compliant'.

</para>

</listitem>

</itemizedlist>

<para>

Most free Java development is grouped under the <ulink

url="http://www.gnu.org/software/java/">Free Java Project</ulink>.

</para>

</section>

<section id="license-concerns"><title>Questions on platforms and license concerns</title>

<section id="java6"><title>Java 7 and 8</title>

<para>

There are binary packages available for the Java 7 and Java 8 platforms since

the Debian 8.0 ('Jessie') release and Debian 9.0 ('Stretch') release.  Once

this is done and you have updated your package database.  You can either

install the Java development kit in Jessie:

</para>

<screen>

apt-get install openjdk-7-jdk

</screen>

<para>

or the Java runtime environment:

</para>

<screen>

apt-get install openjdk-7-jre

</screen>

<para>

Similarly, you can install the Java 8 development kit in Stretch:

</para>

<screen>

apt-get install openjdk-8-jdk

</screen>

<para>

or the Java 8 runtime environment:

</para>

<screen>

apt-get install openjdk-8-jre

</screen>

<para>

You might want to update the alternatives system to have Sun's tools as the

default:

</para>

<screen>

update-java-alternatives -s java-1.7.0-openjdk-amd64

</screen>

<para>

Or for java 8:

</para>

<screen>

update-java-alternatives -s java-1.8.0-openjdk-amd64

</screen>

</section>

<section id="openjdk"><title>Oracle proprietary JVM</title>

<para>

Since the version 7 of the OpenJDK, the proprietary JVM developments are done

on the OpenJDK.  That means that the OpenJDK is strongly tested and high

quality.

</para>

<para>

However, some users might want to use the Oracle JVM for the proprietary

extensions (for example: the browser plugin).  For such need, Debian provides a

tool called <ulink

url="http://packages.debian.org/sid/java-package">java-package</ulink>.  The

program make-jpkg will take an upstream archive and convert it to a Debian

package.  For example:

</para>

<screen>

    make-jpkg jdk-6u31-linux-x64.bin

</screen>

<para>

For more information see <ulink

url="http://www.oracle.com/technetwork/java/index.html">Oracle Technology

Network Java</ulink>.

</para>

</section>

</section>

<section id="s2.4"><title>Making Debian packages for Java programs.</title>

<section id="s2.4.1"><title>Can the package go into main?</title>

<para>

Yes, <emphasis>but only if</emphasis> it can be build and run with Java

programs/tools in main, and if it has a Debian compliant open source license.

If it needs programs from contrib or non-free, then is

<emphasis>must</emphasis> go into contrib or non-free, depending on the license

of the program itself.

</para>

</section>

<section id="s2.4.2"><title>Is there a good example Debian package?</title>

<para>

There are many Debian packages of both Java applications and libraries.  These

may serve as an good starting point, as it can serve as an example for making a

new Debian package.

</para>

<para>

A good start would be to check out the pkg-java project on Salsa: <ulink

url="https://salsa.debian.org/java-team/">https://salsa.debian.org/java-team/</ulink>.

</para>

<para>

Note that there are many ways to make a Debian package, making use of Ant or

Makefiles does not really matter.  But, some tips for good practice are given

on the pkg-java page: <ulink

url="http://pkg-java.alioth.debian.org/developers.html#rules">http://pkg-java.alioth.debian.org/developers.html#rules</ulink>

and <ulink

url="http://pkg-java.alioth.debian.org/building.html">http://pkg-java.alioth.debian.org/building.html</ulink>.

</para>

</section>

<section id="s2.4.3"><title>What tools are available to make maintaining a Java packages easier?</title>

<para>

Both cdbs and debhelper (dh9) have support for ant scripts.  There are also a

number of specialized tools or build helpers.  Have a look at <systemitem

role="package">javahelper</systemitem> or <systemitem

role="package">maven-debian-helper</systemitem>.

</para>

</section>

<section id="s2.4.4"><title>Linking package Javadoc to system javadoc.</title>

<para>

The java-policy mandates that documentation must be linked with the javadoc

installed on the system.  This can be done by passing javadoc the "-link"

argument or by using the <link> tag in ant.  An example:

</para>

<screen>

# command line example of linking against system doc.

javadoc -link /usr/share/doc/default-jdk-doc/api [other arguments]

<!-- Ant example of linking against system doc -->

<javadoc [attributes]>

    <link href="/usr/share/doc/default-jdk-doc/api/" />

    [other tags]

</javadoc>

</screen>

<para>

The documentation must be installed at the time the linking is done; so in the

example cases above the package would need a Build-Depends or a

Build-Depends-Indep on <systemitem role="package">default-jdk-doc</systemitem>.

</para>

<para>

Here is a short list of packages that can be used for reference:

</para>

<itemizedlist>

<listitem>

<para>

<systemitem role="package">libcommons-jci-java</systemitem>

</para>

</listitem>

<listitem>

<para>

<systemitem role="package">libhamcrest-java</systemitem>

</para>

</listitem>

</itemizedlist>

</section>

</section>

</chapter>

<chapter id="ch3"><title>Managing Java (for users and administrators)</title>

<para>

By default Java programs shipped with Debian will use the java in PATH.  Some

of them may respect the JAVA_HOME variable (usually only if upstream supports

this) or have command line arguments to select a different java implementation.

</para>

<para>

Unfortunately not all java implementations work as well as others.  So some

times it may be necessary to change the current java and Debian provides an

easy way to change the default java in PATH by using update-java-alternatives

(from the <systemitem role="package">java-common</systemitem>).  Some examples

of how to do this are:

</para>

<screen>

# List available java implementations

$ sudo update-java-alternatives --list

# Use openjdk-7

$ sudo update-java-alternatives --set java-7-openjdk

</screen>

<para>

For more information, please read the manpage (or the --help output) of

update-java-alternatives.  Also please note that update-java-alternatives is a

frontend for update-alternatives.

</para>

</chapter>

<chapter id="ch4"><title>Java Virtual Machines (JVM)</title>

<section id="s4.1"><title>What JVMs are available in Debian?</title>

<para>

The following JVMs are currently available in Debian Jessie:

</para>

<itemizedlist>

<listitem>

<para>

<systemitem role="package">openjdk-7-jre</systemitem>

</para>

</listitem>

</itemizedlist>

<para>

The following lists JVMs available in Debian 9.0 release ('Stretch'):

</para>

<itemizedlist>

<listitem>

<para>

<systemitem role="package">openjdk-8-jre</systemitem>

</para>

</listitem>

</itemizedlist>

</section>

<section id="s4.2"><title>What Java Compilers are available in Debian?</title>

<itemizedlist>

<listitem>

<para>

<systemitem role="package">openjdk-7-jdk</systemitem>

</para>

</listitem>

<listitem>

<para>

<systemitem role="package">openjdk-8-jdk</systemitem>

</para>

</listitem>

</itemizedlist>

<para>

Compiles Java source to native code, also source to bytecode, or bytecode to

native code.  Please note that the support of the Java language is not

completed.

</para>

</section>

<section id="s4.3"><title>What API do these JVMs provide?</title>

<para>

Note that providing an API does not mean that everything is implemented, and

certainly not implemented correctly.

</para>

</section>

<section id="s4.4"><title>Are there known problems?</title>

<para>

Yes, there are.  Some of these are reported as Debian bugs.  You can look up

the bugs for a specific Debian package at the <ulink

url="http://www.debian.org/Bugs/">Debian Bug Tracking System</ulink>.  As a

quick link, here are some packages:

</para>

<itemizedlist>

<listitem>

<para>

<ulink url="http://bugs.debian.org/java-common">java-common</ulink>

</para>

</listitem>

<listitem>

<para>

<ulink url="http://bugs.debian.org/src:openjdk-7">openjdk-7</ulink>

</para>

</listitem>

<listitem>

<para>

<ulink url="http://bugs.debian.org/src:openjdk-8">openjdk-8</ulink>

</para>

</listitem>

</itemizedlist>

<para>

As common within the Debian project, the developers would appreciate good bug

reports on found problems.  These include the good description of the problem,

the command that gives the problem, the errors given when running the command,

and any other information that might be relevant.  A good tool to report bugs

is <systemitem role="package">reportbug</systemitem>.

</para>

</section>

<section id="s4.5"><title>How can I use the proprietary version of the JDK/JRE from Oracle as a Debian package?</title>

<para>

The package <ulink

url="http://packages.debian.org/wheezy/java-package/">java-package</ulink>

provides an easy way to convert an upstream installer into a Debian package.

It should be as easy as:

</para>

<screen>

make-jpkg ~/Downloads/jdk-6u31-linux-x64.bin

</screen>

<para>

For more information, see this <ulink

url="http://sylvestre.ledru.info/blog/2012/02/29/java_package_replacement_of_sun_java6">Blog

article</ulink>

</para>

</section>

<section id="s4.6"><title>Do I need a JVM to run a Java program in Debian?</title>

<para>

No, you can try to run the applications without a jvm by compiling the source

code to native code is.  However, the usage of the OpenJDK is recommended.

</para>

</section>

</chapter>

<chapter id="browser-java"><title>Java Plugins for Browsers</title>

<itemizedlist>

<listitem>

<para>

You can install the package icedtea-7-plugin or icedtea-8-plugin in

<emphasis>jessie</emphasis>

</para>

</listitem>

</itemizedlist>

</chapter>

<chapter id="ch6"><title>Java Servlets</title>

<section id="s6.1"><title>How can I make Java servlets work?</title>

<para>

You can use:

</para>

<itemizedlist>

<listitem>

<para>

Apache <systemitem role="package">tomcat7</systemitem> from <ulink

url="http://tomcat.apache.org">http://tomcat.apache.org</ulink>.

</para>

</listitem>

<listitem>

<para>

Eclipse <systemitem role="package">jetty</systemitem> from <ulink

url="http://www.eclipse.org/jetty/">http://www.eclipse.org/jetty/</ulink>.

</para>

</listitem>

</itemizedlist>

</section>

</chapter>

<chapter id="ch7"><title>Java Policy</title>

<section id="s7.1"><title>Is there a Java policy for Debian?</title>

<para>

It is still in the works.  The current policy addresses

<emphasis>some</emphasis> of the problems.  It has not been officially

released.  You can find it at <ulink

url="http://www.debian.org/doc/packaging-manuals/java-policy/">http://www.debian.org/doc/packaging-manuals/java-policy/</ulink>.

The Java Policy can also be found in the <systemitem

role="package">java-common</systemitem> package.

</para>

</section>

<section id="s7.2"><title>Are there holes in the Java Policy?</title>

<para>

Yes, some until under discussion.  Please check out the <ulink

url="http://bugs.debian.org/java-common">bugs against the java-common

package</ulink>.  Thus it is <emphasis>very</emphasis> inconvenient to use

several compilers of virtual machines since there is not one CLASSPATH setting

for all of them.

</para>

</section>

</chapter>

<chapter id="ch8"><title>Other Java alternatives for Debian</title>

<para>

If the Java packages provided in Debian are not sufficient for your needs you

might need to take a look at other alternatives.  Please understand that these

alternatives are not supported by the Debian project directly, you might get

help, however, from the debian-java mailing list if you encounter issues with

them.

</para>

<para>

Some of the alternatives presented use Debian packages which is convenient,

since the user/administrator does not need to care on installation issues.

However, mixing packages that come from a source which is not the Debian

project might cause conflicts with your installation some times.  Of course,

Debian tries to integrate as many free software efforts as possible, so some of

the alternatives described below might (if license permits) be included in

Debian in the near future.

</para>

<section id="s8.1"><title>Java programs not yet available on Debian</title>

<para>

The following are programs that have not yet been packaged for Debian nor is

there an installer.  There are quite a lot Java programs out there.

</para>

<para>

A list of missing packages is maintained on the <ulink

url="http://wiki.debian.org/Java/RequestedPackages">Debian Wiki - Java

Packaging Wishlist</ulink>.

</para>

</section>

</chapter>

</book>