From 45fdd4050293b95e21c01cb8cd482408e824acb7 Mon Sep 17 00:00:00 2001
From: Per Bothner <per@bothner.com>
Date: Wed, 7 Jul 2004 18:04:13 -0700
Subject: [PATCH] * gcj.texi (Linking):   New node.  Document -lgij usage.

From-SVN: r84252
---
 gcc/java/ChangeLog |  2 ++
 gcc/java/gcj.texi  | 58 +++++++++++++++++++++++++++++++++++++++-------
 2 files changed, 51 insertions(+), 9 deletions(-)

diff --git a/gcc/java/ChangeLog b/gcc/java/ChangeLog
index 88c1b158221..01c337cf8d0 100644
--- a/gcc/java/ChangeLog
+++ b/gcc/java/ChangeLog
@@ -2,6 +2,8 @@
 
 	* gcj.texi (Invoking gij):  Document new -verbose:class flag.
 
+	* gcj.texi (Linking):   New node.  Document -lgij usage.
+
 2004-07-07  Nathan Sidwell  <nathan@codesourcery.com>
 
 	* java-tree.h (CLASSTYPE_SPUER): Adjust BINFO macros.
diff --git a/gcc/java/gcj.texi b/gcc/java/gcj.texi
index 4eec1a492a6..6c831765c08 100644
--- a/gcc/java/gcj.texi
+++ b/gcc/java/gcj.texi
@@ -161,6 +161,7 @@ options specific to @command{gcj}.
 * Input Options::		How gcj finds files
 * Encodings::                   Options controlling source file encoding
 * Warnings::			Options controlling warnings specific to gcj
+* Linking::			Options for making an executable
 * Code Generation::		Options controlling the output of gcj
 * Configure-time Options::	Options you won't use
 @end menu
@@ -353,21 +354,45 @@ This is the same as @code{-Wredundant-modifiers -Wextraneous-semicolon
 @end table
 
 
-@node Code Generation
-@section Code Generation
+@node Linking
+@section Linking
 
-In addition to the many @command{gcc} options controlling code generation,
-@command{gcj} has several options specific to itself.
+To turn a Java application into an executable program,
+you need to link it with the needed libraries, just as for C or C++.
+The linker by default looks for a global function named @code{main}.
+Since Java does not have global functions, and a
+collection of Java classes may have more than one class with a
+@code{main} method, you need to let the linker know which of those
+@code{main} methods it should invoke when starting the application.
+You can do that in any of these ways:
+
+@itemize @bullet
+@item
+Specify the class containing the desired @code{main} method
+when you link the application, using the @code{--main} flag,
+described below.
+@item
+Link the Java package(s) into a shared library (dll) rather than an
+executable.  Then invoke the application using the @code{gij} program,
+making sure that @code{gij} can find the libraries it needs.
+@item
+Link the Java packages(s) with the flag @code{-lgij}, which links
+in the @code{main} routine from the @code{gij} command.
+This allows you to select the class whose @code{main} method you
+want to run when you run the application.  You can also use
+other @code{gij} flags, such as @code{-D} flags to set properties.
+Using the @code{-lgij} library (rather than the @code{gij} program
+of the previous mechanism) has some advantages: it is compatible with
+static linking, and does not require configuring or installing libraries.
+@end itemize
+
+These @code{gij} options relate to linking an execitable:
 
 @table @gcctabopt
 @item --main=@var{CLASSNAME}
 This option is used when linking to specify the name of the class whose
 @code{main} method should be invoked when the resulting executable is
-run.  @footnote{The linker by default looks for a global function named
-@code{main}.  Since Java does not have global functions, and a
-collection of Java classes may have more than one class with a
-@code{main} method, you need to let the linker know which of those
-@code{main} methods it should invoke when starting the application.}
+run.
 
 @item -D@var{name}[=@var{value}]
 This option can only be used with @code{--main}.  It defines a system
@@ -376,6 +401,21 @@ specified then it defaults to the empty string.  These system properties
 are initialized at the program's startup and can be retrieved at runtime
 using the @code{java.lang.System.getProperty} method.
 
+@item -lgij
+Create an application whose command-line processing is that
+of the @code{gij} command.
+
+This option is an alternative to using @code{--main}; you cannot use both.
+@end table
+
+@node Code Generation
+@section Code Generation
+
+In addition to the many @command{gcc} options controlling code generation,
+@command{gcj} has several options specific to itself.
+
+@table @gcctabopt
+
 @item -C
 This option is used to tell @command{gcj} to generate bytecode
 (@file{.class} files) rather than object code.
-- 
2.30.2