1 This is cp-tools.info, produced by makeinfo version 4.13 from
2 /d/gcc-4.7.2/gcc-4.7.2/libjava/classpath/doc/cp-tools.texinfo.
4 This file documents the Tools included in a standard distribution of
5 the GNU Classpath project deliverables.
7 Copyright (C) 2006, 2007 Free Software Foundation, Inc.
9 INFO-DIR-SECTION GNU Libraries
11 * Classpath Tools: (cp-tools). GNU Classpath Tools Guide
15 File: cp-tools.info, Node: Top, Next: Applet Tools, Prev: (dir), Up: (dir)
17 GNU Classpath Tools Guide
18 *************************
20 This document contains important information you need to know in order
21 to use the tools included in the GNU Classpath project deliverables.
23 The Tools aim at providing a free replacement, similar in their
24 behavior, to their counter-parts found in the Reference Implementation
25 (RI) of the Java Software Development Kit (SDK).
29 * Applet Tools:: Work with applets
30 * Security Tools:: Work securely with Java applications
31 * Other Tools:: Other tools in classpath
32 * I18N Issues:: How to add support for non-English languages
34 --- The Detailed Node Listing ---
38 * appletviewer Tool:: Load applets
39 * gcjwebplugin:: Load applets in a web browser
43 * jarsigner Tool:: Sign and verify .JAR files
44 * keytool Tool:: Manage private keys and public certificates
48 * Common jarsigner Options:: Options used when signing or verifying a file
49 * Signing Options:: Options only used when signing a .JAR file
50 * Verification Options:: Options only used when verifying a .JAR file
54 * Getting Help:: How to get help with keytool commands
55 * Common keytool Options:: Options used in more than one command
56 * Distinguished Names:: X.500 Distinguished Names used in certificates
57 * Add/Update Commands:: Commands for adding data to a Key Store
58 * Export Commands:: Commands for exporting data from a Key Store
59 * Display Commands:: Commands for displaying data in a Key Store
60 * Management Commands:: Commands for managing a Key Store
64 * Command -genkey:: Generate private key and self-signed certificate
65 * Command -import:: Import certificates and certificate replies
66 * Command -selfcert:: Generate self-signed certificate
67 * Command -cacert:: Import a CA Trusted Certificate
68 * Command -identitydb:: Import JDK-1 style identities
72 * Command -certreq:: Generate Certificate Signing Requests (CSR)
73 * Command -export:: Export a certificate in a Key Store
77 * Command -list:: Display information about one or all Aliases
78 * Command -printcert:: Print a certificate or a certificate fingerprint
82 * Command -keyclone:: Clone a Key Entry in a Key Store
83 * Command -storepasswd:: Change the password protecting a Key Store
84 * Command -keypasswd:: Change the password protecting a Key Entry
85 * Command -delete:: Remove an entry in a Key Store
89 * jar Tool:: Archive tool for Java archives
90 * javah Tool:: A java header compiler
91 * gcjh Tool:: A java header compiler (old version)
92 * native2ascii Tool:: An encoding converter
93 * orbd Tool:: An object request broker daemon
94 * serialver Tool:: A serial version command
95 * rmid Tool:: RMI activation daemon
96 * rmiregistry Tool:: Remote object registry
97 * tnameserv Tool:: Naming service
98 * gjdoc Tool:: Documenation generator tool.
100 Generating HTML Documentation
102 * Invoking the Standard Doclet:: How to generate HTML documentation.
103 * Invoking a Custom Doclet:: How to run third-party and other
106 * Option Summary by Type:: Brief list of all options, grouped by type.
107 * Gjdoc Option Summary:: List of all options accepted by Gjdoc.
109 * Source Set Options:: Select the set of source codes to run Gjdoc on.
110 * Source Format Options:: Specify the format of the source codes to document.
112 * Interlinking Options:: Connection your documentation with other projects.
113 * Output Control Options:: Specify the target directory and locale, and more.
114 * Generation Options:: Select which pieces of information to generate.
115 * Decoration Options:: Add or modify some titles, headers and footers or
116 override/amend static resources like stylesheets.
117 * Taglet Options:: Define your own javadoc @tags.
119 * Virtual Machine Options:: Controlling the kind of output:
120 an executable, object files, assembler files,
121 or preprocessed source.
122 * Verbosity Options::
125 * Other Doclets:: Generating Other Output Types.
127 * Built-in Doclets:: Using the Built-in Doclets.
130 * Using IspellDoclet::
131 * Using DebugDoclet::
133 * Third-party Doclets:: Using Third-Party Doclets.
138 * Gjdoc Concepts:: Advanced Concepts.
141 * Doclet Invocation Interface:: Implementing the Doclet Invocation Interface
142 * Using AbstractDoclet:: Deriving Your Doclet from AbstractDoclet.
143 * GNU Doclet SPI:: Preparing the GNU Doclet Service Provider
146 * Taglets:: Adding Custom Tags to the Documentation.
147 * XHTML Fragments:: Well-Formed Documentation Fragments.
148 * First Sentence Detector:: How Gjdoc Determines where the First
150 * Adding Custom Resources:: Adding Images and Other Resources.
154 * Language Resources:: Where resources are located
155 * Message Formats:: How messages are internationalized
158 File: cp-tools.info, Node: Applet Tools, Next: Security Tools, Prev: Top, Up: Top
163 Two Applet Tools are available with GNU Classpath: appletviewer and
166 To avoid conflicts with other implementations, the appletviewer
167 executable is called "gappletviewer".
171 * appletviewer Tool:: Load applets
172 * gcjwebplugin:: Load applets in a web browser
174 If while using these tools you think you found a bug, then please
175 report it at classpath-bugs
176 (http://www.gnu.org/software/classpath/bugs.html).
179 File: cp-tools.info, Node: appletviewer Tool, Next: gcjwebplugin, Prev: Applet Tools, Up: Applet Tools
181 1.1 The `appletviewer' Tool
182 ===========================
186 appletviewer [OPTION]... URL...
187 appletviewer [OPTION]... `-code' CODE
188 appletviewer [OPTION]... `-plugin' INPUT,OUTPUT
190 DESCRIPTION The `appletviewer' tool loads and runs an applet.
192 Use the first form to test applets specified by tag. The URL should
193 resolve to an HTML document from which the `appletviewer' will extract
194 applet tags. The APPLET, EMBED and OBJECT tags are supported. If a
195 given document contains multiple applet tags, all the applets will be
196 loaded, with each applet appearing in its own window. Likewise, when
197 multiple URLs are specified, each applet tag instance is given its own
198 window. If a given document contains no recognized tags the
199 `appletviewer' does nothing.
201 appletviewer http://www.gnu.org/software/classpath/
203 Use the second form to test an applet in development. This form
204 allows applet tag attributes to be supplied on the command line. Only
205 one applet may be specified using the `-code' option. The `-code'
206 option overrides the URL form - any URLs specified will be ignored.
208 appletviewer -code Test.class -param datafile,data.txt
210 `gcjwebplugin' uses the third form to communicate with the
211 `appletviewer' through named pipes.
215 This option is not yet implemented but is provided for
219 Use this option to specify an alternate character encoding for the
225 Use the `-code' option to specify the value of the applet tag CODE
229 Use the `-codebase' option to specify the value of the applet tag
233 Use the `-archive' option to specify the value of the applet tag
237 Use the `-width' option to specify the value of the applet tag
241 Use the `-height' option to specify the value of the applet tag
245 Use the `-param' option to specify values for the NAME and VALUE
246 attributes of an applet PARAM tag.
250 `-plugin INPUT,OUTPUT'
251 `gcjwebplugin' uses the `-plugin' option to specify the named pipe
252 the `appletviewer' should use for receiving commands (INPUT) and
253 the one it should use for sending commands to `gcjwebplugin'
259 Use the `-verbose' option to have the `appletviewer' print
266 Use the `-help' option to have the `appletviewer' print a usage
270 Use the `-version' option to have the `appletviewer' print its
274 Use the `-J' option to pass OPTION to the virtual machine that
275 will run the `appletviewer'. Unlike other options, there must not
276 be a space between the `-J' and OPTION.
280 File: cp-tools.info, Node: gcjwebplugin, Prev: appletviewer Tool, Up: Applet Tools
282 1.2 The `gcjwebplugin' Tool
283 ===========================
285 `gcjwebplugin' is a plugin that adds applet support to web browsers.
286 Currently `gcjwebplugin' only supports Mozilla-based browsers (e.g.,
287 Firefox, Galeon, Mozilla).
290 File: cp-tools.info, Node: Security Tools, Next: Other Tools, Prev: Applet Tools, Up: Top
295 Two Security Tools are available with GNU Classpath: `jarsigner' and
298 To avoid conflicts with other implementations, the jarsigner
299 executable is called `gjarsigner' and the keytool executable is called
304 * jarsigner Tool:: Sign and verify .JAR files
305 * keytool Tool:: Manage private keys and public certificates
307 If while using these tools you think you found a bug, then please
308 report it at classpath-bugs
309 (http://www.gnu.org/software/classpath/bugs.html).
312 File: cp-tools.info, Node: jarsigner Tool, Next: keytool Tool, Prev: Security Tools, Up: Security Tools
314 2.1 The `jarsigner' Tool
315 ========================
317 The `jarsigner' tool is invoked from the command line, in one of two
320 jarsigner [OPTION]... FILE ALIAS
322 jarsigner `-verify' [OPTION]... FILE
324 When the first form is used, the tool signs the designated JAR file.
325 The second form, on the other hand, is used to verify a previously
328 FILE is the .JAR file to process; i.e., to sign if the first syntax
329 form is used, or to verify if the second syntax form is used instead.
331 ALIAS must be a known Alias of a Key Entry in the designated Key
332 Store. The private key material associated with this Alias is then used
333 for signing the designated .JAR file.
337 * Common jarsigner Options:: Options used when signing or verifying a file
338 * Signing Options:: Options only used when signing a .JAR file
339 * Verification Options:: Options only used when verifying a .JAR file
342 File: cp-tools.info, Node: Common jarsigner Options, Next: Signing Options, Prev: jarsigner Tool, Up: jarsigner Tool
347 The following options may be used when the tool is used for either
348 signing, or verifying, a .JAR file.
351 Use this option to force the tool to generate more verbose
352 messages, during its processing.
355 When present, the tool will include -which otherwise it does not-
356 the `.SF' file in the `.DSA' generated file.
359 When present, the tool will include in the `.SF' generated file
360 -which otherwise it does not- a header containing a hash of the
361 whole manifest file. When that header is included, the tool can
362 quickly check, during verification, if the hash (in the header)
363 matches or not the manifest file.
365 `-provider PROVIDER_CLASS_NAME'
366 A fully qualified class name of a Security Provider to add to the
367 current list of Security Providers already installed in the JVM
368 in-use. If a provider class is specified with this option, and was
369 successfully added to the runtime -i.e. it was not already
370 installed- then the tool will attempt to remove this Security
371 Provider before exiting.
374 Prints a help text similar to this one.
378 File: cp-tools.info, Node: Signing Options, Next: Verification Options, Prev: Common jarsigner Options, Up: jarsigner Tool
380 2.1.2 Signing options
381 ---------------------
383 The following options may be specified when using the tool for signing
387 Use this option to specify the location of the key store to use.
388 The default value is a file URL referencing the file named
389 `.keystore' located in the path returned by the call to
390 `java.lang.System#getProperty(String)' using `user.home' as
393 If a URL was specified, but was found to be malformed -e.g.
394 missing protocol element- the tool will attempt to use the URL
395 value as a file-name (with absolute or relative path-name) of a
396 key store -as if the protocol was `file:'.
398 `-storetype STORE_TYPE'
399 Use this option to specify the type of the key store to use. The
400 default value, if this option is omitted, is that of the property
401 `keystore.type' in the security properties file, which is obtained
402 by invoking the static method call `getDefaultType()' in
403 `java.security.KeyStore'.
405 `-storepass PASSWORD'
406 Use this option to specify the password which will be used to
407 unlock the key store. If this option is missing, the User will be
408 prompted to provide a password.
411 Use this option to specify the password which the tool will use to
412 unlock the Key Entry associated with the designated Alias.
414 If this option is omitted, the tool will first attempt to unlock
415 the Key Entry using the same password protecting the key store. If
416 this fails, you will then be prompted to provide a password.
419 Use this option to designate a literal that will be used to
420 construct file names for both the `.SF' and `.DSA' signature
421 files. These files will be generated, by the tool, and placed in
422 the `META-INF' directory of the signed JAR. Permissible
423 characters for NAME must be in the range "a-zA-Z0-9_-". All
424 characters will be converted to upper-case ones.
426 If this option is missing, the first eight characters of the ALIAS
427 argument will be used. When this is the case, any character in
428 ALIAS that is outside the permissible range of characters will be
429 replaced by an underscore.
432 Use this option to specify the file name of the signed JAR. If
433 this option is omitted, then the signed JAR will be named the same
434 as FILE; i.e., the input JAR file will be replaced with the signed
439 File: cp-tools.info, Node: Verification Options, Prev: Signing Options, Up: jarsigner Tool
441 2.1.3 Verification options
442 --------------------------
444 The following options may be specified when using the tool for
445 verification purposes.
448 Use this option to indicate that the tool is to be used for
449 verification purposes.
452 This option is used in conjunction with the `-verbose' option.
453 When present, along with the `-verbose' option, the tool will
454 print more detailed information about the certificates of the
455 signer(s) being processed.
459 File: cp-tools.info, Node: keytool Tool, Prev: jarsigner Tool, Up: Security Tools
461 2.2 The `keytool' Tool
462 ======================
464 Cryptographic credentials, in a Java environment, are usually stored in
465 a Key Store. The Java SDK specifies a Key Store as a persistent
466 container of two types of objects: Key Entries and Trusted
467 Certificates. The security tool `keytool' is a Java-based application
468 for managing those types of objects.
470 A Key Entry represents the private key part of a key-pair used in
471 Public-Key Cryptography, and a signed X.509 certificate which
472 authenticates the public key part for a known entity; i.e. the owner of
473 the key-pair. The X.509 certificate itself contains the public key part
476 A Trusted Certificate is a signed X.509 certificate issued by a
477 trusted entity. The Trust in this context is relative to the User of
478 the `keytool'. In other words, the existence of a Trusted Certificate
479 in the Key Store processed by a `keytool' command implies that the User
480 trusts the Issuer of that Trusted Certificate to also sign, and hence
481 authenticates, other Subjects the tool may process.
483 Trusted Certificates are important because they allow the tool to
484 mechanically construct Chains of Trust starting from one of the Trusted
485 Certificates in a Key Store and ending with a certificate whose Issuer
486 is potentially unknown. A valid chain is an ordered list, starting with
487 a Trusted Certificate (also called the anchor), ending with the target
488 certificate, and satisfying the condition that the Subject of
489 certificate `#i' is the Issuer of certificate `#i + 1'.
491 The `keytool' is invoked from the command line as follows:
493 keytool [COMMAND] ...
495 Multiple COMMANDs may be specified at once, each complete with its
496 own options. `keytool' will parse all the arguments, before processing,
497 and executing, each `COMMAND'. If an exception occurs while executing
498 one COMMAND `keytool' will abort. Note however that because the
499 implementation of the tool uses code to parse command line options that
500 also supports GNU-style options, you have to separate each command
501 group with a double-hyphen; e.g
503 keytool -list -- -printcert -alias mykey
505 Here is a summary of the commands supported by the tool:
507 1. Add/Update commands
508 `-genkey [OPTION]...'
509 Generate a new Key Entry, eventually creating a new key store.
511 `-import [OPTION]...'
512 Add, to a key store, Key Entries (private keys and
513 certificate chains authenticating the public keys) and
514 Trusted Certificates (3rd party certificates which can be
515 used as Trust Anchors when building chains-of-trust).
517 `-selfcert [OPTION]...'
518 Generate a new self-signed Trusted Certificate.
520 `-cacert [OPTION]...'
521 Import a CA Trusted Certificate.
523 `-identitydb [OPTION]...'
525 Import a JDK 1.1 style Identity Database.
528 `-certreq [OPTION]...'
529 Issue a Certificate Signing Request (CSR) which can be then
530 sent to a Certification Authority (CA) to issue a certificate
531 signed (by the CA) and authenticating the Subject of the
534 `-export [OPTION]...'
535 Export a certificate from a key store.
539 Print one or all certificates in a key store to `STDOUT'.
541 `-printcert [OPTION]...'
542 Print a human-readable form of a certificate, in a designated
545 4. Management commands
546 `-keyclone [OPTION]...'
547 Clone a Key Entry in a key store.
549 `-storepasswd [OPTION]...'
550 Change the password protecting a key store.
552 `-keypasswd [OPTION]...'
553 Change the password protecting a Key Entry in a key store.
555 `-delete [OPTION]...'
556 Delete a Key Entry or a Trusted Certificate from a key store.
560 * Getting Help:: How to get help with keytool commands
561 * Common keytool Options:: Options used in more than one command
562 * Distinguished Names:: X.500 Distinguished Names used in certificates
563 * Add/Update Commands:: Commands for adding data to a Key Store
564 * Export Commands:: Commands for exporting data from a Key Store
565 * Display Commands:: Commands for displaying data in a Key Store
566 * Management Commands:: Commands for managing a Key Store
569 File: cp-tools.info, Node: Getting Help, Next: Common keytool Options, Prev: keytool Tool, Up: keytool Tool
574 To get a general help text about the tool, use the `-help' option; e.g.
578 To get more specific help text about one of the tool's command use
579 the `-help' option for that command; e.g.
581 `keytool -genkey -help'
583 In both instances, the tool will print a help text and then will
584 exit the running JVM.
586 It is worth noting here that the help messages printed by the tool
587 are I18N-ready. This means that if/when the contents of the tool's
588 Message Bundle properties file are available in languages other than
589 English, you may see those messages in that language.
592 File: cp-tools.info, Node: Common keytool Options, Next: Distinguished Names, Prev: Getting Help, Up: keytool Tool
597 The following `OPTION's are used in more than one `COMMAND'. They are
598 described here to reduce redundancy.
601 Every entry, be it a Key Entry or a Trusted Certificate, in a key
602 store is uniquely identified by a user-defined ALIAS string. Use
603 this option to specify the ALIAS to use when referring to an entry
604 in the key store. Unless specified otherwise, a default value of
605 `mykey' shall be used when this option is omitted from the command
609 Use this option to specify the canonical name of the key-pair
610 generation algorithm. The default value for this option is `DSS'
611 (a synonym for the Digital Signature Algorithm also known as DSA).
614 Use this option to specify the number of bits of the shared
615 modulus (for both the public and private keys) to use when
616 generating new keys. A default value of `1024' will be used if
617 this option is omitted from the command line.
619 `-validity DAY_COUNT'
620 Use this option to specify the number of days a newly generated
621 certificate will be valid for. The default value is `90' (days) if
622 this option is omitted from the command line.
624 `-storetype STORE_TYPE'
625 Use this option to specify the type of the key store to use. The
626 default value, if this option is omitted, is that of the property
627 `keystore.type' in the security properties file, which is obtained
628 by invoking the static method call `getDefaultType()' in
629 `java.security.KeyStore'.
631 `-storepass PASSWORD'
632 Use this option to specify the password protecting the key store.
633 If this option is omitted from the command line, you will be
634 prompted to provide a password.
637 Use this option to specify the location of the key store to use.
638 The default value is a file URL referencing the file named
639 `.keystore' located in the path returned by the call to
640 `java.lang.System#getProperty(String)' using `user.home' as
643 If a URL was specified, but was found to be malformed -e.g.
644 missing protocol element- the tool will attempt to use the URL
645 value as a file-name (with absolute or relative path-name) of a
646 key store -as if the protocol was `file:'.
648 `-provider PROVIDER_CLASS_NAME'
649 A fully qualified class name of a Security Provider to add to the
650 current list of Security Providers already installed in the JVM
651 in-use. If a provider class is specified with this option, and was
652 successfully added to the runtime -i.e. it was not already
653 installed- then the tool will attempt to removed this Security
654 Provider before exiting.
657 Use this option to designate a file to use with a command. When
658 specified with this option, the value is expected to be the fully
659 qualified path of a file accessible by the File System. Depending
660 on the command, the file may be used as input or as output. When
661 this option is omitted from the command line, `STDIN' will be used
662 instead, as the source of input, and `STDOUT' will be used instead
663 as the output destination.
666 Unless specified otherwise, use this option to enable more verbose
671 File: cp-tools.info, Node: Distinguished Names, Next: Add/Update Commands, Prev: Common keytool Options, Up: keytool Tool
673 2.2.3 X.500 Distinguished Names
674 -------------------------------
676 A Distinguished Name (or DN) MUST be supplied with some of the
677 `COMMAND's using a `-dname' option. The syntax of a valid value for
678 this option MUST follow RFC-2253 specifications. Namely the following
679 components (with their accepted meaning) will be recognized. Note that
680 the component name is case-insensitive:
683 The Common Name; e.g. `host.domain.com'
686 The Organizational Unit; e.g. `IT Department'
689 The Organization Name; e.g. `The Sample Company'
692 The Locality Name; e.g. `Sydney'
695 The State Name; e.g. `New South Wales'
698 The 2-letter Country identifier; e.g. `AU'
700 When specified with a `-dname' option, each pair of component/value
701 will be separated from the other with a comma. Each component and value
702 pair MUST be separated by an equal sign. For example, the following is
704 CN=host.domain.com, O=The Sample Company, L=Sydney, ST=NSW, C=AU
706 If the Distinguished Name is required, and no valid default value can
707 be used, the tool will prompt you to enter the information through the
711 File: cp-tools.info, Node: Add/Update Commands, Next: Export Commands, Prev: Distinguished Names, Up: keytool Tool
713 2.2.4 Add/Update commands
714 -------------------------
718 * Command -genkey:: Generate private key and self-signed certificate
719 * Command -import:: Import certificates and certificate replies
720 * Command -selfcert:: Generate self-signed certificate
721 * Command -cacert:: Import a CA Trusted Certificate
722 * Command -identitydb:: Import JDK-1 style identities
725 File: cp-tools.info, Node: Command -genkey, Next: Command -import, Prev: Add/Update Commands, Up: Add/Update Commands
727 2.2.4.1 The `-genkey' command
728 .............................
730 Use this command to generate a new key-pair (both private and public
731 keys), and save these credentials in the key store as a Key Entry,
732 associated with the designated (if was specified with the `-alias'
733 option) or default (if the `-alias' option is omitted) Alias.
735 The private key material will be protected with a user-defined
736 password (see `-keypass' option). The public key on the other hand will
737 be part of a self-signed X.509 certificate, which will form a 1-element
738 chain and will be saved in the key store.
741 For more details *note ALIAS: alias.
744 For more details *note ALGORITHM: keyalg.
747 For more details *note KEY_SIZE: keysize.
750 The canonical name of the digital signature algorithm to use for
751 signing certificates. If this option is omitted, a default value
752 will be chosen based on the type of the key-pair; i.e., the
753 algorithm that ends up being used by the -keyalg option. If the
754 key-pair generation algorithm is `DSA', the value for the
755 signature algorithm will be `SHA1withDSA'. If on the other hand
756 the key-pair generation algorithm is `RSA', then the tool will use
757 `MD5withRSA' as the signature algorithm.
760 This a mandatory value for the command. If no value is specified
761 -i.e. the `-dname' option is omitted- the tool will prompt you to
762 enter a Distinguished Name to use as both the Owner and Issuer of
763 the generated self-signed certificate.
765 For more details *note X.500 DISTINGUISHED NAME: dn.
768 Use this option to specify the password which the tool will use to
769 protect the newly created Key Entry.
771 If this option is omitted, you will be prompted to provide a
774 `-validity DAY_COUNT'
775 For more details *note DAY_COUNT: validity.
777 `-storetype STORE_TYPE'
778 For more details *note STORE_TYPE: storetype.
781 For more details *note URL: keystore.
783 `-storepass PASSWORD'
784 For more details *note PASSWORD: storepass.
786 `-provider PROVIDER_CLASS_NAME'
787 For more details *note PROVIDER_CLASS_NAME: provider.
790 For more details *note verbose::.
794 File: cp-tools.info, Node: Command -import, Next: Command -selfcert, Prev: Command -genkey, Up: Add/Update Commands
796 2.2.4.2 The `-import' command
797 .............................
799 Use this command to read an X.509 certificate, or a PKCS#7 Certificate
800 Reply from a designated input source and incorporate the certificates
803 If the Alias does not already exist in the key store, the tool
804 treats the certificate read from the input source as a new Trusted
805 Certificate. It then attempts to discover a chain-of-trust, starting
806 from that certificate and ending at another Trusted Certificate,
807 already stored in the key store. If the `-trustcacerts' option is
808 present, an additional key store, of type `JKS' named `cacerts', and
809 assumed to be present in `${JAVA_HOME}/lib/security' will also be
810 consulted if found -`${JAVA_HOME}' refers to the location of an
811 installed Java Runtime Environment (JRE). If no chain-of-trust can be
812 established, and unless the `-noprompt' option has been specified, the
813 certificate is printed to `STDOUT' and the user is prompted for a
816 If Alias exists in the key store, the tool will treat the
817 certificate(s) read from the input source as a Certificate Reply, which
818 can be a chain of certificates, that eventually would replace the chain
819 of certificates associated with the Key Entry of that Alias. The
820 substitution of the certificates only occurs if a chain-of-trust can be
821 established between the bottom certificate of the chain read from the
822 input file and the Trusted Certificates already present in the key
823 store. Again, if the `-trustcacerts' option is specified, additional
824 Trusted Certificates in the same `cacerts' key store will be
825 considered. If no chain-of-trust can be established, the operation will
829 For more details *note ALIAS: alias.
832 For more details *note FILE: file.
835 Use this option to specify the password which the tool will use to
836 protect the Key Entry associated with the designated Alias, when
837 replacing this Alias' chain of certificates with that found in the
840 If this option is omitted, and the chain-of-trust for the
841 certificate reply has been established, the tool will first
842 attempt to unlock the Key Entry using the same password protecting
843 the key store. If this fails, you will then be prompted to provide
847 Use this option to prevent the tool from prompting the user.
850 Use this option to indicate to the tool that a key store, of type
851 `JKS', named `cacerts', and usually located in `lib/security' in
852 an installed Java Runtime Environment should be considered when
853 trying to establish chain-of-trusts.
855 `-storetype STORE_TYPE'
856 For more details *note STORE_TYPE: storetype.
859 For more details *note URL: keystore.
861 `-storepass PASSWORD'
862 For more details *note PASSWORD: storepass.
864 `-provider PROVIDER_CLASS_NAME'
865 For more details *note PROVIDER_CLASS_NAME: provider.
868 For more details *note verbose::.
872 File: cp-tools.info, Node: Command -selfcert, Next: Command -cacert, Prev: Command -import, Up: Add/Update Commands
874 2.2.4.3 The `-selfcert' command
875 ...............................
877 Use this command to generate a self-signed X.509 version 1 certificate.
878 The newly generated certificate will form a chain of one element which
879 will replace the previous chain associated with the designated Alias
880 (if `-alias' option was specified), or the default Alias (if `-alias'
884 For more details *note ALIAS: alias.
887 The canonical name of the digital signature algorithm to use for
888 signing the certificate. If this option is omitted, a default
889 value will be chosen based on the type of the private key
890 associated with the designated Alias. If the private key is a
891 `DSA' one, the value for the signature algorithm will be
892 `SHA1withDSA'. If on the other hand the private key is an `RSA'
893 one, then the tool will use `MD5withRSA' as the signature
897 Use this option to specify the Distinguished Name of the newly
898 generated self-signed certificate. If this option is omitted, the
899 existing Distinguished Name of the base certificate in the chain
900 associated with the designated Alias will be used instead.
902 For more details *note X.500 DISTINGUISHED NAME: dn.
904 `-validity DAY_COUNT'
905 For more details *note DAY_COUNT: validity.
908 Use this option to specify the password which the tool will use to
909 unlock the Key Entry associated with the designated Alias.
911 If this option is omitted, the tool will first attempt to unlock
912 the Key Entry using the same password protecting the key store. If
913 this fails, you will then be prompted to provide a password.
915 `-storetype STORE_TYPE'
916 For more details *note STORE_TYPE: storetype.
919 For more details *note URL: keystore.
921 `-storepass PASSWORD'
922 For more details *note PASSWORD: storepass.
924 `-provider PROVIDER_CLASS_NAME'
925 For more details *note PROVIDER_CLASS_NAME: provider.
928 For more details *note verbose::.
932 File: cp-tools.info, Node: Command -cacert, Next: Command -identitydb, Prev: Command -selfcert, Up: Add/Update Commands
934 2.2.4.4 The `-cacert' command
935 .............................
937 Use this command to import, a CA certificate and add it to the key
938 store as a Trusted Certificate. The Alias for this new entry will be
939 constructed from the FILE's base-name after replacing hyphens and dots
942 This command is useful when used in a script that recursively visits
943 a directory of CA certificates to populate a `cacerts.gkr' Key Store of
944 trusted certificates which can then be used commands that specify the
945 `-trustcacerts' option.
948 For more details *note FILE: file.
950 `-storetype STORE_TYPE'
951 For more details *note STORE_TYPE: storetype.
954 For more details *note URL: keystore.
956 `-storepass PASSWORD'
957 For more details *note PASSWORD: storepass.
959 `-provider PROVIDER_CLASS_NAME'
960 For more details *note PROVIDER_CLASS_NAME: provider.
963 For more details *note verbose::.
967 File: cp-tools.info, Node: Command -identitydb, Prev: Command -cacert, Up: Add/Update Commands
969 2.2.4.5 The `-identitydb' command
970 .................................
974 Use this command to import a JDK 1.1 style Identity Database.
977 For more details *note FILE: file.
979 `-storetype STORE_TYPE'
980 For more details *note STORE_TYPE: storetype.
983 For more details *note URL: keystore.
985 `-storepass PASSWORD'
986 For more details *note PASSWORD: storepass.
988 `-provider PROVIDER_CLASS_NAME'
989 For more details *note PROVIDER_CLASS_NAME: provider.
992 For more details *note verbose::.
996 File: cp-tools.info, Node: Export Commands, Next: Display Commands, Prev: Add/Update Commands, Up: keytool Tool
998 2.2.5 Export commands
999 ---------------------
1003 * Command -certreq:: Generate Certificate Signing Requests (CSR)
1004 * Command -export:: Export a certificate in a Key Store
1007 File: cp-tools.info, Node: Command -certreq, Next: Command -export, Prev: Export Commands, Up: Export Commands
1009 2.2.5.1 The `-certreq' command
1010 ..............................
1012 Use this command to generate a PKCS#10 Certificate Signing Request
1013 (CSR) and write it to a designated output destination. The contents of
1014 the destination should look something like the following:
1016 -----BEGIN NEW CERTIFICATE REQUEST-----
1017 MI...QAwXzEUMBIGA1UEAwwLcnNuQGdudS5vcmcxGzAZBgNVBAoMElUg
1018 Q2...A0GA1UEBwwGU3lkbmV5MQwwCgYDVQQIDANOU1cxCzAJBgNVBACC
1020 FC...IVwNVOfQLRX+O5kAhQ/a4RTZme2L8PnpvgRwrf7Eg8D6w==
1021 -----END NEW CERTIFICATE REQUEST-----
1023 IMPORTANT: Some documentation (e.g. RSA examples) claims that the
1024 `Attributes' field, in the CSR is `OPTIONAL' while RFC-2986 implies the
1025 opposite. This implementation considers this field, by default, as
1026 `OPTIONAL', unless the option `-attributes' is specified on the command
1030 For more details *note ALIAS: alias.
1033 The canonical name of the digital signature algorithm to use for
1034 signing the certificate. If this option is omitted, a default
1035 value will be chosen based on the type of the private key
1036 associated with the designated Alias. If the private key is a
1037 `DSA' one, the value for the signature algorithm will be
1038 `SHA1withDSA'. If on the other hand the private key is an `RSA'
1039 one, then the tool will use `MD5withRSA' as the signature
1043 For more details *note FILE: file.
1046 Use this option to specify the password which the tool will use to
1047 unlock the Key Entry associated with the designated Alias.
1049 If this option is omitted, the tool will first attempt to unlock
1050 the Key Entry using the same password protecting the key store. If
1051 this fails, you will then be prompted to provide a password.
1053 `-storetype STORE_TYPE'
1054 For more details *note STORE_TYPE: storetype.
1057 For more details *note URL: keystore.
1059 `-storepass PASSWORD'
1060 For more details *note PASSWORD: storepass.
1062 `-provider PROVIDER_CLASS_NAME'
1063 For more details *note PROVIDER_CLASS_NAME: provider.
1066 For more details *note verbose::.
1069 Use this option to force the tool to encode a `NULL' DER value in
1070 the CSR as the value of the `Attributes' field.
1074 File: cp-tools.info, Node: Command -export, Prev: Command -certreq, Up: Export Commands
1076 2.2.5.2 The `-export' command
1077 .............................
1079 Use this command to export a certificate stored in a key store to a
1080 designated output destination, either in binary format (if the `-v'
1081 option is specified), or in RFC-1421 compliant encoding (if the `-rfc'
1082 option is specified instead).
1085 For more details *note ALIAS: alias.
1088 For more details *note FILE: file.
1090 `-storetype STORE_TYPE'
1091 For more details *note STORE_TYPE: storetype.
1094 For more details *note URL: keystore.
1096 `-storepass PASSWORD'
1097 For more details *note PASSWORD: storepass.
1099 `-provider PROVIDER_CLASS_NAME'
1100 For more details *note PROVIDER_CLASS_NAME: provider.
1103 Use RFC-1421 specifications when encoding the output.
1106 Output the certificate in binary DER encoding. This is the default
1107 output format of the command if neither `-rfc' nor `-v' options
1108 were detected on the command line. If both this option and the
1109 `-rfc' option are detected on the command line, the tool will opt
1110 for the RFC-1421 style encoding.
1114 File: cp-tools.info, Node: Display Commands, Next: Management Commands, Prev: Export Commands, Up: keytool Tool
1116 2.2.6 Display commands
1117 ----------------------
1121 * Command -list:: Display information about one or all Aliases
1122 * Command -printcert:: Print a certificate or a certificate fingerprint
1125 File: cp-tools.info, Node: Command -list, Next: Command -printcert, Prev: Display Commands, Up: Display Commands
1127 2.2.6.1 The `-list' command
1128 ...........................
1130 Use this command to print one or all of a key store entries to
1131 `STDOUT'. Usually this command will only print a fingerprint of the
1132 certificate, unless either the `-rfc' or the `-v' option is specified.
1135 If this option is omitted, the tool will print ALL the entries
1136 found in the key store.
1138 For more details *note ALIAS: alias.
1140 `-storetype STORE_TYPE'
1141 For more details *note STORE_TYPE: storetype.
1144 For more details *note URL: keystore.
1146 `-storepass PASSWORD'
1147 For more details *note PASSWORD: storepass.
1149 `-provider PROVIDER_CLASS_NAME'
1150 For more details *note PROVIDER_CLASS_NAME: provider.
1153 Use RFC-1421 specifications when encoding the output.
1156 Output the certificate in human-readable format. If both this
1157 option and the `-rfc' option are detected on the command line, the
1158 tool will opt for the human-readable form and will not abort the
1163 File: cp-tools.info, Node: Command -printcert, Prev: Command -list, Up: Display Commands
1165 2.2.6.2 The `-printcert' command
1166 ................................
1168 Use this command to read a certificate from a designated input source
1169 and print it to `STDOUT' in a human-readable form.
1172 For more details *note FILE: file.
1175 For more details *note verbose::.
1179 File: cp-tools.info, Node: Management Commands, Prev: Display Commands, Up: keytool Tool
1181 2.2.7 Management commands
1182 -------------------------
1186 * Command -keyclone:: Clone a Key Entry in a Key Store
1187 * Command -storepasswd:: Change the password protecting a Key Store
1188 * Command -keypasswd:: Change the password protecting a Key Entry
1189 * Command -delete:: Remove an entry in a Key Store
1192 File: cp-tools.info, Node: Command -keyclone, Next: Command -storepasswd, Prev: Management Commands, Up: Management Commands
1194 2.2.7.1 The `-keyclone' command
1195 ...............................
1197 Use this command to clone an existing Key Entry and store it under a
1198 new (different) Alias protecting, its private key material with
1199 possibly a new password.
1202 For more details *note ALIAS: alias.
1205 Use this option to specify the new Alias which will be used to
1206 identify the cloned copy of the Key Entry.
1209 Use this option to specify the password which the tool will use to
1210 unlock the Key Entry associated with the designated Alias.
1212 If this option is omitted, the tool will first attempt to unlock
1213 the Key Entry using the same password protecting the key store. If
1214 this fails, you will then be prompted to provide a password.
1217 Use this option to specify the password protecting the private key
1218 material of the newly cloned copy of the Key Entry.
1220 `-storetype STORE_TYPE'
1221 For more details *note STORE_TYPE: storetype.
1224 For more details *note URL: keystore.
1226 `-storepass PASSWORD'
1227 For more details *note PASSWORD: storepass.
1229 `-provider PROVIDER_CLASS_NAME'
1230 For more details *note PROVIDER_CLASS_NAME: provider.
1233 For more details *note verbose::.
1237 File: cp-tools.info, Node: Command -storepasswd, Next: Command -keypasswd, Prev: Command -keyclone, Up: Management Commands
1239 2.2.7.2 The `-storepasswd' command
1240 ..................................
1242 Use this command to change the password protecting a key store.
1245 The new, and different, password which will be used to protect the
1246 designated key store.
1248 `-storetype STORE_TYPE'
1249 For more details *note STORE_TYPE: storetype.
1252 For more details *note URL: keystore.
1254 `-storepass PASSWORD'
1255 For more details *note PASSWORD: storepass.
1257 `-provider PROVIDER_CLASS_NAME'
1258 For more details *note PROVIDER_CLASS_NAME: provider.
1261 For more details *note verbose::.
1265 File: cp-tools.info, Node: Command -keypasswd, Next: Command -delete, Prev: Command -storepasswd, Up: Management Commands
1267 2.2.7.3 The `-keypasswd' command
1268 ................................
1270 Use this command to change the password protecting the private key
1271 material of a designated Key Entry.
1274 For more details *note ALIAS: alias.
1276 Use this option to specify the password which the tool will use to
1277 unlock the Key Entry associated with the designated Alias.
1279 If this option is omitted, the tool will first attempt to unlock
1280 the Key Entry using the same password protecting the key store. If
1281 this fails, you will then be prompted to provide a password.
1284 The new, and different, password which will be used to protect the
1285 private key material of the designated Key Entry.
1287 `-storetype STORE_TYPE'
1288 For more details *note STORE_TYPE: storetype.
1291 For more details *note URL: keystore.
1293 `-storepass PASSWORD'
1294 For more details *note PASSWORD: storepass.
1296 `-provider PROVIDER_CLASS_NAME'
1297 For more details *note PROVIDER_CLASS_NAME: provider.
1300 For more details *note verbose::.
1304 File: cp-tools.info, Node: Command -delete, Prev: Command -keypasswd, Up: Management Commands
1306 2.2.7.4 The `-delete' command
1307 .............................
1309 Use this command to delete a designated key store entry.
1312 For more details *note ALIAS: alias.
1314 `-storetype STORE_TYPE'
1315 For more details *note STORE_TYPE: storetype.
1318 For more details *note URL: keystore.
1320 `-storepass PASSWORD'
1321 For more details *note PASSWORD: storepass.
1323 `-provider PROVIDER_CLASS_NAME'
1324 For more details *note PROVIDER_CLASS_NAME: provider.
1327 For more details *note verbose::.
1331 File: cp-tools.info, Node: Other Tools, Next: I18N Issues, Prev: Security Tools, Up: Top
1336 This is a list of currently undocumented classpath tools: jar, javah,
1337 gcjh, native2ascii, orbd, serialver, rmid, rmiregistry and tnameserv.
1341 * jar Tool:: Archive tool for Java archives
1342 * javah Tool:: A java header compiler
1343 * gcjh Tool:: A java header compiler (old version)
1344 * native2ascii Tool:: An encoding converter
1345 * orbd Tool:: An object request broker daemon
1346 * serialver Tool:: A serial version command
1347 * rmid Tool:: RMI activation daemon
1348 * rmiregistry Tool:: Remote object registry
1349 * tnameserv Tool:: Naming service
1350 * gjdoc Tool:: A documentation generator
1353 File: cp-tools.info, Node: jar Tool, Next: javah Tool, Up: Other Tools
1358 `gjar' is an implementation of Sun's jar utility that comes with the
1361 If any file is a directory then it is processed recursively. The
1362 manifest file name and the archive file name needs to be specified in
1363 the same order the `-m' and `-f' flags are specified.
1371 List table of contents for archive.
1374 Extract named (or all) files from archive.
1377 Update existing archive.
1380 Compute archive index.
1382 Operation modifiers:
1385 Specify archive file name.
1388 Store only; use no ZIP compression.
1391 Generate verbose output on standard output.
1394 Do not create a manifest file for the entries.
1397 Include manifest information from specified MANIFEST file.
1399 File name selection:
1402 Change to the DIR and include the following FILE.
1405 Read the names of the files to add to the archive from stdin. This
1406 option is supported only in combination with `-c' or `-u'. Non
1407 standard option added in the GCC version.
1412 Print help text, then exit.
1415 Print version number, then exit.
1418 Pass argument to the Java runtime.
1423 File: cp-tools.info, Node: javah Tool, Next: gcjh Tool, Prev: jar Tool, Up: Other Tools
1425 3.2 The `javah' Tool
1426 ====================
1428 The `gjavah' program is used to generate header files from class files.
1429 It can generate both CNI and JNI header files, as well as stub
1430 implementation files which can be used as a basis for implementing the
1431 required native methods.
1434 Set output directory.
1437 Set output file (only one of `-d' or `-o' may be used).
1443 Operate on all class files under directory DIR.
1446 Emit stub implementation.
1449 Emit JNI stubs or header (default).
1452 Emit CNI stubs or header (default JNI).
1458 Output files should always be written.
1465 Add directory to class path.
1467 `-bootclasspath PATH'
1468 Set the boot class path.
1471 Set the extension directory path.
1475 Print help text, then exit.
1478 Print version number, then exit.
1481 Pass argument to the Java runtime.
1486 File: cp-tools.info, Node: gcjh Tool, Next: native2ascii Tool, Prev: javah Tool, Up: Other Tools
1491 The `gcjh' program is used to generate header files from class files.
1492 It can generate both CNI and JNI header files, as well as stub
1493 implementation files which can be used as a basis for implementing the
1494 required native methods. It is similar to `javah' but has slightly
1495 different command line options, and defaults to CNI.
1497 See `javah' for a full description; this page only lists the
1498 additional options provided by `gcjh'.
1502 Insert TEXT into class body.
1505 Append TEXT after class declaration.
1508 Insert TEXT as a `friend' declaration.
1511 Insert TEXT before start of class.
1513 Compatibility options (unused)
1519 Unused compatibility option.
1523 Print help text, then exit.
1526 Print version number, then exit.
1529 Pass argument to the Java runtime.
1531 javac(1), javah(1), ...
1534 File: cp-tools.info, Node: native2ascii Tool, Next: orbd Tool, Prev: gcjh Tool, Up: Other Tools
1536 3.4 The `native2ascii' Tool
1537 ===========================
1542 Set the encoding to use.
1545 Convert from encoding to native.
1549 Print help text, then exit.
1552 Print version number, then exit.
1555 Pass argument to the Java runtime.
1560 File: cp-tools.info, Node: orbd Tool, Next: serialver Tool, Prev: native2ascii Tool, Up: Other Tools
1562 3.5 The `orbd' object request broker daemon
1563 ===========================================
1567 `-ORBInitialPort PORT'
1568 Port on which persistent naming service is to be started.
1571 File in which to store persistent naming service's IOR reference
1574 Directory in which to store persistent data.
1577 Restart persistent naming service, clearing persistent naming
1582 Print help text, then exit.
1585 Print version number, then exit.
1588 Pass argument to the Java runtime.
1593 File: cp-tools.info, Node: serialver Tool, Next: rmid Tool, Prev: orbd Tool, Up: Other Tools
1595 3.6 The `serialver' version command
1596 ===================================
1598 Print the serialVersionUID of the specified classes.
1601 Class path to use to find classes.
1605 Print help text, then exit.
1608 Print version number, then exit.
1611 Pass argument to the Java runtime.
1616 File: cp-tools.info, Node: rmid Tool, Next: rmiregistry Tool, Prev: serialver Tool, Up: Other Tools
1618 3.7 The `rmid' RMI activation system daemon
1619 ===========================================
1621 `rmiregistry' starts a remote object registry on the current host. If
1622 no port number is specified, then port 1099 is used.
1624 Activation process control:
1626 Port on which activation system is to be started.
1629 Restart activation system, clearing persistent naming database, if
1633 Stop activation system.
1637 Make activation system persistent.
1640 Directory in which to store persistent data.
1644 Log binding events to standard out.
1648 Print help text, then exit.
1651 Print version number, then exit.
1654 Pass argument to the Java runtime.
1659 File: cp-tools.info, Node: rmiregistry Tool, Next: tnameserv Tool, Prev: rmid Tool, Up: Other Tools
1661 3.8 The `rmiregistry' Tool
1662 ==========================
1664 `grmiregistry' starts a remote object registry on the current host. If
1665 no port number is specified, then port 1099 is used.
1667 Registry process control:
1669 Restart RMI naming service, clearing persistent naming database, if
1673 Stop RMI naming service.
1677 Make RMI naming service persistent.
1680 Directory in which to store persistent data.
1684 Log binding events to standard out.
1688 Print help text, then exit.
1691 Print version number, then exit.
1694 Pass argument to the Java runtime.
1699 File: cp-tools.info, Node: tnameserv Tool, Next: gjdoc Tool, Prev: rmiregistry Tool, Up: Other Tools
1701 3.9 The `tnameserv' Tool
1702 ========================
1706 `-ORBInitialPort PORT'
1707 Port on which naming service is to be started.
1710 File in which to store naming service's IOR reference.
1714 Print help text, then exit.
1717 Print version number, then exit.
1720 Pass argument to the Java runtime.
1724 Info entry for `gjdoc'. Please report bugs to
1725 `http://savannah.gnu.org/bugs/?group=classpath'. Julian Scheid
1728 File: cp-tools.info, Node: gjdoc Tool, Prev: tnameserv Tool, Up: Other Tools
1730 4 Generating HTML Documentation
1731 *******************************
1733 Gjdoc can be used in two ways: as a stand-alone documentation tool, or
1734 as a driver for a user-specified Doclet. *Note Other Doclets::.
1736 In the default mode, Gjdoc will use the Standard Doclet `HtmlDoclet'
1737 to generate a set of HTML pages. The canonical usage is:
1739 gjdoc -s src/java/ -all -d api-docs/
1741 Here, `src/java/' is the root of your source code class hierarchy,
1742 `-all' means that all valid Java files found under this root directory
1743 should be processed, and `api-docs/' is the directory where the
1744 generated documentation should be placed.
1746 To learn more about running Doclets other than the Standard Doclet,
1747 refer to the manual. *Note Invoking a Custom Doclet::.
1751 * Invoking the Standard Doclet:: How to generate HTML documentation.
1752 * Invoking a Custom Doclet:: How to run third-party and other
1755 * Option Summary by Type:: Brief list of all options, grouped by type.
1756 * Gjdoc Option Summary:: List of all options accepted by Gjdoc.
1758 * Source Set Options:: Select the set of source codes to run Gjdoc on.
1759 * Source Format Options:: Specify the format of the source codes to document.
1761 * Interlinking Options:: Connection your documentation with other projects.
1762 * Output Control Options:: Specify the target directory and locale, and more.
1763 * Generation Options:: Select which pieces of information to generate.
1764 * Decoration Options:: Add or modify some titles, headers and footers or
1765 override/amend static resources like stylesheets.
1766 * Taglet Options:: Define your own javadoc @tags
1768 * Virtual Machine Options::
1769 * Verbosity Options::
1772 * Other Doclets:: Generating Other Output Types
1773 * Gjdoc Concepts:: Advanced Concepts
1776 File: cp-tools.info, Node: Invoking the Standard Doclet, Next: Invoking a Custom Doclet, Up: gjdoc Tool
1778 4.1 Invoking the Standard Doclet
1779 ================================
1781 Running the Gjdoc Standard Doclet `HtmlDoclet' is the default mode of
1782 operation for Gjdoc. This section lists the command line options you
1783 can specify in this mode. It doesn't distinguish between general Gjdoc
1784 options and options specific to the Standard Doclet.
1786 If you want to learn which options are accepted when Gjdoc is used as
1787 a doclet driver, *Note Invoking a Custom Doclet::.
1791 * Source Set Options:: Select the set of source codes to run Gjdoc on.
1792 * Source Format Options:: Specify the format of the source codes to document.
1794 * Output Control Options:: Specify the target directory and locale, and more.
1795 * Generation Options:: Select which pieces of information to generate.
1796 * Decoration Options:: Add or modify some titles, headers and footers or
1797 override/amend static resources like stylesheets.
1798 * Taglet Options:: Define your own javadoc @tags
1800 * Virtual Machine Options::
1804 File: cp-tools.info, Node: Option Summary by Type, Next: Gjdoc Option Summary, Prev: Invoking a Custom Doclet, Up: gjdoc Tool
1806 4.2 Option Summary by Type
1807 ==========================
1809 Here is a summary of all the options of both Gjdoc and the Standard
1810 Doclet, grouped by type. Explanations are in the following sections.
1812 _Source Set Options_
1813 *Note Options For Specifying the Source Files To Operate on:
1815 -sourcepath PATHLIST -subpackages PKGLIST -exclude PKGLIST
1817 _Source Format Options_
1818 *Note Options For Specifying the Source Format: Source Format
1820 -source RELEASE -encoding ENCODING -breakiterator
1822 _Interlinking Options_
1823 *Note Options For Specifying the Source Files To Operate on:
1824 Interlinking Options.
1825 -link URL -linkoffline URL FILE -noqualifier PKG:PKG:...
1827 _Generation Options_
1828 *Note Options Controlling What is Included in the Output:
1830 -author -licensetext -use -version -splitindex -noindex
1831 -nodeprecated -nodeprecatedlist -nohelp -nonavbar
1832 -nosince -notree -public -protected -package -private
1833 -docfilessubdirs -excludedocfilessubdir DIRNAME
1837 *Note Options Controlling the Output: Generation Options.
1838 -d -locale NAME -charset CHARSET -docencoding CHARSET
1839 -validhtml -baseurl URL
1841 _Decoration Options_
1842 -windowtitle TEXT -doctitle TEXT -title TEXT
1843 -header TEXT -footer TEXT -bottom TEXT
1844 -helpfile FILE -stylesheetfile FILE -addstylesheet FILE
1845 -group GROUPHEADING PKGPATTERN:PKGPATTERN:...
1848 *Note Options For Specifying user-defined Taglets: Taglet Options.
1849 -tagletpath -taglet CLASSNAME -tag TAGSPEC
1852 *Note Options For Specifying the Doclet to use: Doclet Options.
1853 -docletpath -doclet CLASSNAME
1856 *Note Options Controlling Gjdoc Behavior: Verbosity Options.
1859 _Virtual Machine Options_
1860 *Note Options Controlling Gjdoc Behavior: Virtual Machine Options.
1871 * Virtual Machine Options:: Controlling the kind of output:
1872 an executable, object files, assembler files,
1873 or preprocessed source.
1876 File: cp-tools.info, Node: Source Set Options, Next: Source Format Options, Prev: Gjdoc Option Summary, Up: gjdoc Tool
1878 4.3 Selecting which Source Files to Process
1879 ===========================================
1883 `-sourcepath PATHLIST'
1884 Look for source files in the specified directory or directories.
1886 PATHLIST should be one or more directory paths separated by your
1887 platform's path separator (usually `:' or `;').
1889 If this option is not given, `gjdoc' will look for source files in
1890 the current directory.
1892 The directories specified should be root directories in terms of
1893 the Java package system. For example, if you want to generate
1894 documentation for classes in package `foo.bar', you must specify
1895 the directory containing the top-level ``foo'' sub-directory, not
1896 the directory ``foo/bar/'' in which the Java source files reside.
1898 The short-hand alias `-s' is specific to `gjdoc' and not
1899 compatible to Sun `javadoc'.
1902 _[EXPERIMENTAL]_ Process all valid Java source files found in the
1903 directories listed in the source path and their sub-directories.
1905 This is an option specific to `gjdoc' and not compatible to Sun
1908 `-subpackages PKG:PKG:...'
1909 Process the classes in the given Java packages and all
1910 sub-packages, recursively. Note that multiple package names must
1911 be separated with colons instead of whitespace.
1913 `-exclude PKG:PKG:...'
1914 Do not process classes in the given Java packages and all
1915 sub-packages, recursively. This option can be used in conjunction
1916 with `-all' or `-subpackages' in order to exclude individual
1917 packages or package sub-trees from the output.
1920 Process all classes in the given Java packages.
1923 Process the classes in the given Java source files.
1926 File: cp-tools.info, Node: Source Format Options, Next: Interlinking Options, Prev: Source Set Options, Up: gjdoc Tool
1928 4.4 Specifying the Format of Input Files
1929 ========================================
1932 Assume that the source files are targeted at the given release of
1935 RELEASE should be the version number of a Java platform release in
1936 the format MAJOR.MINOR, for example `1.4'.
1938 This option is currently ignored except that an error is raised if
1939 a release number other than `1.2', `1.3' or `1.4' is specified.
1942 Assume that the source files are encoded using CHARSET.
1944 Examples for CHARSET are `US-ASCII', `ISO-8859-1' or `UTF-8'.
1946 The semantics of CHARSET are identical to those of
1947 `java.nio.charset.Charset.forName(String)'.
1950 Use the locale's java.text.BreakIterator instead of the internal
1951 first sentence detector.
1953 By default, `gjdoc' uses an internal algorithm to determine where
1954 a sentence ends. When this option is given, it will instead use
1955 the `java.text.BreakIterator' instance for the locale given with
1956 `-locale' (or the default locale).
1958 This option should be specified when applying `gjdoc' to source
1959 code commented in a non-latin language for which the default first
1960 sentence detector does not work. For all other cases, the default
1961 (do not use BreakIterator) produces better results at the time of
1965 File: cp-tools.info, Node: Interlinking Options, Next: Output Control Options, Prev: Source Format Options, Up: gjdoc Tool
1967 4.5 Interlinking with other Documentation Sets
1968 ==============================================
1971 Create hyperlinks to another documentation set.
1973 By default, `gjdoc' will only create hyperlinks to classes in the
1974 source set. Use this option to additionally create hyperlinks to
1975 classes covered by the specified documentation set.
1977 URL should be the root URL of the other documentation set. For
1978 example, to add hyperlinks to GNU Classpath, specify the following:
1980 -link http://developer.classpath.org/doc/
1982 The `-link' option can be specified multiple times.
1984 Note that specifying the `-link' option will cause an HTTP access
1985 every time gjdoc is invoked. You can use `-linkoffline' instead to
1988 `-linkoffline URL FILE'
1989 Create hyperlinks to another documentation set which is also
1990 present on the local file system.
1992 This option works exactly like `-link', except that it accesses
1993 the local file system instead of the network for determining which
1994 classes are covered by the linked documentation set.
1996 When using `-linkoffline' the remote documentation set is not
1997 accessed at all, which can significantly speed up generation time
1998 depending on your network connection. The generated hyperlinks to
1999 the documentation set however refer to the remote set, not to the
2000 local one, so that you can distribute the documentation without
2001 any further dependencies.
2003 The `-linkoffline' option can be specified multiple times.
2005 `-noqualifier PKG:PKG:...'
2006 Do not qualify names of classes in the given packages with their
2009 By default, a class name is displayed unqualified only if the
2010 class is part of the source set or a linked documentation set, and
2011 qualified with the name of its containing package if it is not.
2012 You can use this option to force unqualified names for classes
2013 even if they are not part of the documentation set.
2015 For example, usually a reference to the String class is represented
2016 fully-qualified as `java.lang.String' (unless you link to the
2017 appropriate documentation set using `-link') because it isn't part
2018 of the documentation set. You can specify `-noqualifier
2019 java.lang' to render the same references just as `String'.
2021 Note that for all unqualified class names, a tooltip is provided
2022 when you place your mouse pointer over it in the HTML
2025 `-noqualifier `all''
2026 Omit package name qualifier from all class names.
2028 Specify this option to omit package name qualifiers altogether,
2032 File: cp-tools.info, Node: Generation Options, Next: Decoration Options, Prev: Output Control Options, Up: gjdoc Tool
2034 4.6 Selecting which Information to Generate
2035 ===========================================
2038 Only include public members of public classes in the output. By
2039 default, protected class members are included as well.
2042 Include public or protected members of public classes in the
2043 output. This is the default.
2046 Include public, protected and package-private members of public and
2047 package-private classes.
2050 Include all classes and class members regardless of their access
2054 Generate one index page per letter instead of a single, monolithic
2057 By default, the index created by the Standard Doclet contains all
2058 entries on a single page. This is fine for small documentation
2059 sets, but for large sets you should specify this option.
2062 Ignore `@since' tags in javadoc comments.
2064 By default, the generated output contains sections listing the
2065 version of your API since which the package, class or class member
2066 in question exists when this tag is encountered. Specify this
2067 option to omit this information.
2070 Do not generate any tree pages.
2072 By default, the generated output includes one inheritance tree per
2073 package, and - if the documentation set consists of multiple
2074 packages - a page with the full inheritance tree. Specify this
2075 option to omit generation of these pages.
2078 Do not output the alphabetical index.
2080 By default, gjdoc generates an alphabetical index of all program
2081 elements in the documentation set (packages, classes, inner
2082 classes, constructors, methods, and fields). Specify this option
2083 to omit this information.
2086 Do not generate the help page.
2088 This option is currently ignored as the Standard Doclet doesn't
2089 provide a help page.
2092 Do not output inline information about deprecated packages,
2093 classes or class members.
2095 By default, the Standard Doclet adds a highlighted paragraph with
2096 deprecation information to the description of each deprecated
2097 program element. Specify this option to omit this information.
2100 Do not output the summary page for deprecated API elements.
2102 By default, the Standard Doclet generates a page listing all
2103 deprecated API elements along with a deprecation description which
2104 usually includes the reason for deprecation and possible
2105 alternatives. Specify this option to omit this information.
2108 Do not output the navigation bar, header, and footer.
2110 By default, each output page is equipped with a top navigation bar
2111 (which may include a user-specified header) and a bottom navigation
2112 bar (which may include a user-specified footer). Specify this
2113 option to omit this decoration.
2116 Omit all documentation text from the generated files and output
2117 only declarations and program element relationships.
2119 This option is here for compatibility with `javadoc'. If you plan
2120 on extracting information about your project via `gjdoc', you
2121 should consider using a different Doclet for your purposes
2122 instead, for example XmlDoclet. You could also use the Doclet API
2123 directly by implementing a new Doclet.
2126 Generate a page with syntax-highlighted source code for each class.
2127 By default, this page is not generated.
2129 The source code can be accessed by clicking on the button labelled
2130 "Source" in the navigation bar, or by clicking on the name of a
2131 constructor, field, method, or inner class in the detail section
2132 of a class documentation page.
2135 Generate a page with cross-reference information. By default, this
2136 page is not generated.
2138 The cross-reference information can be accessed by clicking on the
2139 button labelled `Use' in the navigation bar.
2141 The `Use' page lists all classes/interfaces in the documentation
2142 set that extend/implement the class (type) in question; fields of
2143 the type; methods or constructors accepting a parameter of the
2144 type; methods returning the type; and methods or constructors
2148 Include author information in the output.
2150 When specified, author information as specified using the
2151 `@author' tag in javadoc comments is incorporated into the output.
2152 By default, `@author' tags are ignored.
2155 Include version information in the output.
2157 When specified, version information as specified using the
2158 `@version' tag in javadoc comments is incorporated into the
2159 output. By default, `@version' tags are ignored.
2162 Assume that the first comment in each source file contains the
2163 license text, and add license information to the footer of each
2164 generated class page.
2166 This is an option specific to `gjdoc' and not compatible to Sun
2169 This option is intended for use with free and open source projects
2170 where source code is typically prefixed with a boilerplate license
2171 comment, when there are legal reasons for including the license in
2175 Recursively copy all files in the `doc-files' sub-directory of each
2178 Usually, only the files in the `doc-files' sub-directory are copied
2179 without descending recursively.
2181 *Note Adding Custom Resources::.
2183 `-excludedocfilessubdir NAME:NAME:...'
2184 Do not copy some directories directly under the `doc-files'
2185 sub-directories when descending recursively.
2187 The argument to this option should be a colon-separated list of
2190 This option only makes sense if `-docfilessubdirs' is also
2191 specified. In this case, any sub-directory located directly
2192 beneath a `doc-files' directory is omitted if listed.
2196 File: cp-tools.info, Node: Taglet Options, Next: Virtual Machine Options, Prev: Decoration Options, Up: gjdoc Tool
2198 4.7 Custom Documentation Tags
2199 =============================
2201 `-tagletpath PATHLIST'
2202 Search PATHLIST when loading subsequent Taglet classes specified
2205 PATHLIST should be one or more paths to a directory or jar file,
2206 separated by your platform's path separator (usually `:' or `;').
2211 CLASSNAME should be the fully-qualified name of a Java class
2212 implementing `com.sun.tools.doclets.Taglet'.
2214 The Taglet classes will be loaded from the classpath specified
2215 using `-tagletpath', from the classpath specified using
2216 `-classpath' and from the default classpath.
2218 See the documentation of `com.sun.tools.doclets.Taglet' for
2219 further information.
2221 Note that for simple tags, there is also `-tag'.
2224 Register a generic Taglet.
2226 The format of TAGSPEC must be `<tagname>:<flags>:"<taghead>"'.
2228 TAGNAME is the tag name to match, without the leading @ sign.
2230 FLAGS is one or more of the following characters, where each
2231 character specifies a source code context in which the tag is to be
2253 types (classes, interfaces, exceptions, errors)
2256 special character which temporarily disables the Taglet
2259 TAGHEAD is the string to display in the header of the section
2260 devoted to the tag in question.
2262 For example, to define a tag matching `@cvsid' which is to be
2263 accepted in overview, package and type pages and which is labelled
2264 with the header `CVS ID', you would specify:
2266 -tag cvsid:tpo:"CVS ID"
2268 Let's say that a class javadoc comment contains
2270 @cvsid $Id: cp-tools.texinfo,v 1.7 2008/08/13 13:32:05 jsumali Exp $
2272 Then the HTML output will contain something like
2275 $Id: cp-tools.texinfo,v 1.7 2008/08/13 13:32:05 jsumali Exp $
2278 File: cp-tools.info, Node: Doclet Options, Next: Other Doclets, Prev: Verbosity Options, Up: gjdoc Tool
2280 4.8 Running Other Doclets
2281 =========================
2283 `-docletpath PATHLIST'
2284 Search PATHLIST when loading classes for the Doclet specified
2287 PATHLIST should be one or more paths to a directory or jar file,
2288 separated by your platform's path separator (usually `:' or `;').
2291 Run the specified doclet instead of the standard HtmlDoclet.
2293 CLASSNAME should be the fully-qualified name of a class which has
2294 a public default constructor and contain a method with the
2295 following signature:
2297 import com.sun.javadoc.RootDoc;
2298 public static boolean start(RootDoc rootDoc)
2300 The Doclet classes will be loaded from the classpath specified
2301 using `-docletpath', from the classpath specified using
2302 `-classpath' and from the default classpath.
2304 The `start' method should process the information exposed by the
2305 Doclet API via `rootDoc' and return `true' on success, `false' on
2308 If you are using a third-party doclet, refer to its documentation
2309 for further instructions. Note that support for third-party
2310 doclets is experimental. Please report any problems you
2311 encounter, or provide feedback when successfully running
2312 third-party applets.
2314 This option can be specified multiple times, in which case all
2315 doclets are executed with the same information tree exposed via
2316 the Doclet API for each Doclet run.
2320 File: cp-tools.info, Node: Decoration Options, Next: Taglet Options, Prev: Generation Options, Up: gjdoc Tool
2322 4.9 Adding Information to the Output
2323 ====================================
2326 Use TEXT as the browser window title prefix.
2328 When specified, the browser window title for each page will be
2329 prefixed with TEXT instead of the default string `Generated API
2332 TEXT should be plain text (it should not contain HTML tags).
2335 Set the header text of the overview page to TEXT.
2337 TEXT should be a short plain text string.
2339 When generating documentation for a single package, specifying this
2340 option forces generation of the overview page.
2343 Add HTMLTEXT to the right upper corner of every generated page.
2344 HTMLTEXT is usually set to the name of the project being
2348 Add HTMLTEXT to the right bottom corner of every generated page.
2349 HTMLTEXT is often set to the same value as for `-header'.
2352 Add HTMLTEXT to the very bottom of every generated page, spanning
2353 the whole width of the page. When specified, HTMLTEXT usually
2354 consists of a copyright notice and/or links to other project pages.
2356 `-addstylesheet FILE'
2357 Augment the default CSS style sheets with the user-specified
2360 The given stylesheet is simply loaded by each HTML page in
2361 addition to the default ones, as the last stylesheet.
2363 Note that the CSS cascading rules apply. That is, your style
2364 properties will only be assigned if they have a higher cascading
2365 order than `gjdoc''s default style. One simple way to make sure
2366 that this is the case is to declare your overrides `!important'.
2368 See `http://www.w3.org/TR/REC-CSS2/cascade.html#cascading-order'.
2370 `-group HEADING PKGWILDCARD:PKGWILDCARD:...'
2371 Arrange the given packages in a separate group on the overview
2374 The first argument should be a short plain text which is used as
2375 the title of the package group. The second argument should be a
2376 colon-separated list of package wildcards. The group will consist
2377 of all packages in the documentation set whose name matches any of
2378 the given wildcards.
2380 There is only one wildcard character, `*', which matches both
2381 letters in package name components and the `.' separating package
2382 name components. For example, `j*regex' would match package
2383 `java.util.regex'. A more useful example would be `javax.swing*'
2384 to match `javax.swing' and all of its sub-packages.
2386 This option can be given multiple times.
2388 FIXME: Information about group nesting here.
2390 gjdoc -group "Core Classes" 'java*' \
2391 -group "Swing" 'javax.swing*' \
2392 -group "XML APIs" 'javax.xml*' \
2393 -group "Other Extensions" javax* \
2397 Add the XHTML body fragment from FILE to the overview page.
2399 FILE should contain an XHTML fragment with the HTML `body' tag as
2400 the root node. *Note XHTML Fragments::.
2402 This option can be used to supply a description of the
2403 documentation set as a whole.
2405 When specified, the first sentence of the fragment will be put
2406 above the tables listing the documented packages, along with a
2407 link to the full copy of the fragment which is put below the
2408 tables. *Note First Sentence Detector::.
2410 When generating documentation for a single package, specifying this
2411 option forces generation of the overview page.
2413 `-stylesheetfile FILE'
2414 Use the CSS stylesheet in FILE instead of the default CSS
2417 If you only want to override parts of the default stylesheets, use
2418 `-addstylesheet' instead.
2421 _Deprecated._ Use `-doctitle' TEXT instead.
2424 This option is currently ignored.
2426 When implemented, it will use the XHTML fragment in FILE for the
2427 help page contents instead of the default help text.
2431 File: cp-tools.info, Node: Output Control Options, Next: Generation Options, Prev: Interlinking Options, Up: gjdoc Tool
2433 4.10 Controlling the Output.
2434 ============================
2437 Place all output files into DIRECTORY (and sub-directories).
2438 DIRECTORY will be created if it does not exist, including all
2439 non-existing parent directories and all required sub-directories.
2441 If not specified, output will be placed into the current directory.
2444 Use locale NAME instead of the default locale for all purposes.
2446 NAME should be a locale specifier in the form `ll_CC[_VAR]' where
2447 `ll' is a lowercase two-letter ISO-639 language code, `CC' is an
2448 optional uppercase two-letter ISO-3166 country code, and `VAR' is
2449 an optional variant code. For example, `en' specifies English,
2450 `en_US' specifies US English, and `en_US_WIN' specifies a deviant
2451 variant of the US English locale.
2453 Note that the semantics of this option correspond exactly to those
2454 of the constructors of class `java.util.Locale'.
2456 This option currently only determines which Collator is being used
2457 for sorting output elements. This means that the locale will only
2458 have an effect when you are using non-ASCII characters in
2462 _Deprecated._ Override the specified encoding in output XHTML
2463 files with the one given by `charset'.
2465 If this option is not given, the encoding specification in output
2466 XHTML is chosen to match the encoding used when writing the file
2467 (the encoding given with `-docencoding', or your platform's default
2470 The semantics for CHARSET are specified here:
2471 `http://www.w3.org/TR/2000/REC-xml-20001006#NT-EncName'. For all
2472 practical purposes, they are identical to those of the other
2473 options accepting charset parameters.
2475 This option is here for compatibility with `javadoc' and should be
2478 `-docencoding CHARSET'
2479 Use the given charset encoding when writing output files instead of
2480 your platform's default encoding.
2482 Examples for CHARSET are `US-ASCII', `ISO-8859-1' or `UTF-8'.
2484 The semantics of this option correspond exactly to those of the
2485 constructors of class `java.util.Locale'.
2488 Force generation of valid XHTML code. This breaks compatibility to
2489 the traditional Javadoc tool to some extent.
2491 If this option is specified, anchor names will be mangled so that
2492 they are valid according to the XHTML 1.1 specification. However,
2493 a documentation set generated with this option cannot be linked to
2494 properly using the traditional Javadoc tool. It can be linked to
2495 just fine using Gjdoc, though.
2497 Without this option, anchor names for executable class members use
2498 the traditional format, for example: "foo(String,int[])". This is
2499 compatible to the traditional Javadoc tool, but according to both
2500 the HTML 4.0 and XHTML 1.0 and 1.1 specifications, this format
2501 includes illegal characters. Parentheses, square brackets, and
2502 the comma are not allowed in anchor names.
2505 Hardwire a page URL relative to URL into each generated page.
2507 If you are generating documentation which will exclusively be
2508 available at a certain URL, you should use this option to specify
2511 This can help avoid certain redirect attacks used by spammers, and
2512 it can be helpful for certain web clients.
2516 File: cp-tools.info, Node: Verbosity Options, Next: Doclet Options, Prev: Virtual Machine Options, Up: gjdoc Tool
2518 4.11 Verbosity Options
2519 ======================
2522 Suppress all output except for warnings and error messages.
2525 Be very verbose about what `gjdoc' is doing.
2527 This option is currently ignored.
2531 File: cp-tools.info, Node: Virtual Machine Options, Next: Verbosity Options, Prev: Taglet Options, Up: gjdoc Tool
2533 4.12 Virtual Machine Options
2534 ============================
2536 Sun's `javadoc' tool seems to be based on `javac' and as such it seems
2537 to operate on the VM level. `gjdoc', in contrast, is a pure Java
2540 Therefore, `gjdoc' can only fake, or simulate, the following
2543 `-classpath PATHLIST'
2544 Set the Virtual Machine `classpath' to PATHLIST.
2546 In most cases you should use `-docletpath' or `-tagletpath'
2547 instead of this option.
2549 PATHLIST should be one or more paths to a directory or jar file,
2550 separated by your platform's path separator (usually `:' or `;').
2552 If this option is not intercepted at the wrapper level, `gjdoc'
2553 currently fakes it by calling
2554 `System.setProperty("java.class.path", PATHLIST);' and outputs a
2557 `-bootclasspath PATHLIST'
2558 Set the Virtual Machine `bootclasspath' to PATHLIST.
2560 If this option is not intercepted at the wrapper level, `gjdoc'
2564 Pass an arbitrary parameter to the Virtual Machine `gjdoc' runs on.
2566 If this option is not intercepted at the wrapper level, `gjdoc'
2567 tries to emulate the option and outputs a warning.
2569 Currently, only the VM option `-D' for setting system properties
2574 File: cp-tools.info, Node: Invoking a Custom Doclet, Next: Option Summary by Type, Prev: Invoking the Standard Doclet, Up: gjdoc Tool
2576 4.13 Invoking a Custom Doclet
2577 =============================
2579 For invoking one of the other doclets shipping with `gjdoc' or a
2580 third-party doclet, the canonical usage is:
2582 gjdoc -s src/java/ -all \
2583 -docletpath /path/to/doclet.jar -doclet foo.BarDoclet \
2584 (more Gjdoc core options and Doclet-specific options here)
2586 `/path/to/doclet.jar' is a placeholder for a class path specifying
2587 where the Doclet classes and dependencies can be found and
2588 `foo.BarDoclet' is the fully-qualified name of the Doclet's main class.
2591 File: cp-tools.info, Node: Gjdoc Option Summary, Next: Source Set Options, Prev: Option Summary by Type, Up: gjdoc Tool
2593 4.14 Gjdoc Option Summary
2594 =========================
2597 File: cp-tools.info, Node: Other Doclets, Next: Gjdoc Concepts, Prev: Doclet Options, Up: gjdoc Tool
2599 5 Generating Other Output Types
2600 *******************************
2604 * Built-in Doclets::
2605 * Third-party Doclets::
2608 File: cp-tools.info, Node: Built-in Doclets, Next: Third-party Doclets, Up: Other Doclets
2610 5.1 Using the Built-in Doclets
2611 ==============================
2616 * Using TexiDoclet::
2617 * Using IspellDoclet::
2618 * Using DebugDoclet::
2621 File: cp-tools.info, Node: Using TexiDoclet, Next: Using XmlDoclet, Up: Built-in Doclets
2623 5.1.1 TexiDoclet: Generating Info, PDF, and other formats
2624 ---------------------------------------------------------
2629 File: cp-tools.info, Node: Using XmlDoclet, Next: Using IspellDoclet, Prev: Using TexiDoclet, Up: Built-in Doclets
2631 5.1.2 XmlDoclet: Generating XML Documentation
2632 ---------------------------------------------
2637 File: cp-tools.info, Node: Using IspellDoclet, Next: Using DebugDoclet, Prev: Using XmlDoclet, Up: Built-in Doclets
2639 5.1.3 IspellDoclet: Spell-checking Source Code
2640 ----------------------------------------------
2645 File: cp-tools.info, Node: Using DebugDoclet, Prev: Using IspellDoclet, Up: Built-in Doclets
2647 5.1.4 DebugDoclet: Inspecting the Doclet API
2648 --------------------------------------------
2653 File: cp-tools.info, Node: Third-party Doclets, Prev: Built-in Doclets, Up: Other Doclets
2655 5.2 Using Third-Party Doclets
2656 =============================
2665 File: cp-tools.info, Node: DocBook Doclet, Next: PDFDoclet, Up: Third-party Doclets
2667 5.2.1 DocBook Doclet
2668 --------------------
2673 File: cp-tools.info, Node: PDFDoclet, Next: JUnitDoclet, Prev: DocBook Doclet, Up: Third-party Doclets
2681 File: cp-tools.info, Node: JUnitDoclet, Prev: PDFDoclet, Up: Third-party Doclets
2689 File: cp-tools.info, Node: Gjdoc Concepts, Prev: Other Doclets, Up: gjdoc Tool
2699 * First Sentence Detector::
2700 * Adding Custom Resources::
2703 File: cp-tools.info, Node: Taglets, Next: Writing Doclets, Up: Gjdoc Concepts
2705 6.1 Adding Custom Tags to the Documentation
2706 ===========================================
2711 File: cp-tools.info, Node: Writing Doclets, Next: XHTML Fragments, Prev: Taglets, Up: Gjdoc Concepts
2716 If the various Doclets already available don't suit your needs, you can
2717 write a custom Doclet yourself.
2721 * Doclet Invocation Interface::
2722 * Using AbstractDoclet::
2726 File: cp-tools.info, Node: Doclet Invocation Interface, Next: Using AbstractDoclet, Up: Writing Doclets
2728 6.2.1 Implementing the Doclet Invocation Interface
2729 --------------------------------------------------
2731 A Doclet is a class that contains a method with the following signature:
2733 public static boolean start(RootDoc rootDoc);
2735 ROOTDOC is the root of an object hierarchy containing the
2736 information `gjdoc' extracted from the source files. See the Doclet
2737 API for more details.
2739 `start' should process all the information and return `true' on
2740 success, `false' on failure.
2742 For printing status information, the Doclet should use methods
2743 `printNotice', `printWarning' and `printError' instead of `System.err'.
2744 The Doclet can opt to use `System.out' for redirectable output.
2747 File: cp-tools.info, Node: Using AbstractDoclet, Next: GNU Doclet SPI, Prev: Doclet Invocation Interface, Up: Writing Doclets
2749 6.2.2 Deriving Your Doclet from AbstractDoclet
2750 ----------------------------------------------
2752 You may want your Doclet to provide functionality similar to
2753 HtmlDoclet. For example, you may want it to support Taglets, generate
2754 Index, Tree, and Uses pages, or show other cross-reference information
2755 like `Overrides' and `All Implementing Classes'.
2757 This information is not directly provided by the Doclet API, so your
2758 Doclet would normally have to assemble it itself. For example, it
2759 would have to add the names of all program elements to a list and sort
2760 this list in order to create the Index page.
2762 If you want to provide this information or part of it, you should
2763 consider deriving your class from
2764 `gnu.classpath.tools.doclets.AbstractDoclet'. This class provides the
2767 * Handles options `-tag', `-taglet', `-tagletpath' (Taglets)
2769 * Provides standard taglets for @version, @author, @since, @serial,
2770 @deprecated, @see, @param, @return and handles all related options
2771 (`-version', `-author', `-nosince', `-nodeprecated')
2773 * Handles option `-d' (destination directory)
2775 * Handles option `-noqualifier' (classes to omit qualifier for)
2777 * Handles options `-docfilessubdirs' and `-excludedocfilessubdir'
2780 * Can generate a full index or an index split by first letter
2782 * Can generate a full tree and package trees
2784 * Can generate cross-reference information
2786 * Can aggregate interface information (all superinterfaces, all
2787 subinterfaces, all implementing classes)
2789 * Provides convenient access to constructors, fields, methods, and
2790 inner classes sorted by name/signature instead of the default sort
2793 * Provides various other convenience methods
2796 If you derive from `AbstractDoclet', there are a number of things
2797 you need to take care of:
2800 you should not implement the `start(RootDoc)' method as it is
2801 already defined by `AbstractDoclet' so that it can care about parsing
2804 Instead, you implement method `run()', `getOptions()' and the other
2805 abstract methods to define your Doclet's behavior.
2807 Note that all information provided by `AbstractDoclet' is evaluated
2808 lazily. That is, if your Doclet doesn't need to create an Index page,
2809 then `AbstractDoclet' will not spend resources on creating the
2810 corresponding information.
2812 See the API documentation for
2813 `gnu.classpath.tools.doclets.AbstractDoclet' for more details.
2815 You should be aware that if you base your Doclet on `AbstractDoclet'
2816 then you have to bundle this and all related classes with your Doclet,
2817 with all implications such as possible licensing issues. Otherwise,
2818 your Doclet will only be runnable on `gjdoc' and not on other
2819 documentation systems. Also note that `AbstractDoclet' has not been
2820 extensively tested in environments other than `gjdoc'.
2823 File: cp-tools.info, Node: GNU Doclet SPI, Prev: Using AbstractDoclet, Up: Writing Doclets
2825 6.2.3 Preparing for the GNU Doclet Service Provider Interface
2826 -------------------------------------------------------------
2828 In addition to the standard Doclet invocation interface described
2829 above, `gjdoc' also offers a Service Provider Interface conforming to
2830 the Java standard. Adding support for this interface to your Doclet
2831 simplifies usage for `gjdoc' users because it makes your Doclet
2834 In order to provide the alternate interface, you have to add a class
2835 implementing `gnu.classpath.tools.gjdoc.spi.DocletSpi' to your Doclet
2836 classes, and bundle all Doclet classes in a Jar file along with a file
2837 named `META_INF/services/gnu.classpath.tools.gjdoc.spi.DocletSpi' which
2838 contains the name of your class implementing DocletSpi on a single line.
2840 Note that if your Doclet depends on third-party classes bundled in
2841 separate Jar files, you can link in these classes using the
2842 `Class-path:' Manifest attribute of your Doclet Jar.
2844 Your Doclet can then be invoked in one of the following ways:
2845 gjdoc -docletjar /path/to/doclet.jar
2846 gjdoc -docletpath /path/to/doclet.jar -docletname DOCLETNAME
2847 gjdoc -docletname DOCLETNAME
2849 Here, DOCLETNAME is the name of your doclet as returned by
2850 `DocletSpi.getDocletName()'.
2852 The last example will only work if your Doclet Jar is in `gjdoc''s
2853 `doclets' directory or if it is on the classpath.
2856 File: cp-tools.info, Node: XHTML Fragments, Next: First Sentence Detector, Prev: Writing Doclets, Up: Gjdoc Concepts
2858 6.3 Well-formed Documentation Fragments
2859 =======================================
2861 For many Doclets it is advantagous if the HTML code in the comments and
2862 HTML code passed via the command line is well-formed. For example,
2863 HtmlDoclet outputs XHTML code, and XmlDoclet XML code, both of which
2864 results in invalid files if the user-specified HTML isn't wellformed.
2866 Unfortunately, comments were never required to contain well-formed
2867 HTML code, which means that every Doclet must deal with non-wellformed
2870 The `gjdoc' built-in Doclets deal with this problem by "fixing" the
2871 HTML code - making sure that all tags are closed, attribute values are
2872 provided and quoted, tags are properly nested, etc.
2874 This approach works OK in most instances, but since it uses some
2875 crude heuristics it can sometimes produce undesirable result.
2877 Therefore, in order to make sure that your comments are always
2878 properly formatted, make sure they are well-formed as described in
2879 XHTML 1.0: Documents must be well-formed (http://www.w3.org/TR/xhtml1/#h-4.1).
2881 In addition, you should use meaningful tags instead of text
2882 formatting tags to make your output look better in other output formats
2883 derived from your HTML code. For example, you should use the <em> tag
2884 instead of <b> if you want to emphasize text.
2887 File: cp-tools.info, Node: First Sentence Detector, Next: Adding Custom Resources, Prev: XHTML Fragments, Up: Gjdoc Concepts
2889 6.4 How Gjdoc Determines where the First Sentence Ends
2890 ======================================================
2892 For a package, class or member summary, `gjdoc' only shows the first
2893 sentence of the documentation comment in question. Because `gjdoc' is
2894 not human, it is not always obvious to `gjdoc' where the first sentence
2897 You might be tempted to say that the first sentence ends at the first
2898 occurrence of a punctuation character like `.' or `!'. However,
2899 consider examples like this:
2900 This work, by Thomas J. Shahan et al., is about the middle ages.
2902 As you can see, it is not trivial to determine the end of the
2905 `gjdoc' gives you the choice between two approaches. By default it
2906 uses built-in heuristics which should be compatible to Sun's `javadoc'
2907 tool. This approach works quiet well in most cases, at least for
2910 Alternatively, you can specify option `-breakiterator' in which case
2912 `java.text.BreakIterator.getSentenceInstance(LOCALE).next()' to find
2913 the end of sentence, where LOCALE is the locale specified by option
2914 `-locale' or the default locale if none specified.
2916 _NOT YET IMPLEMENTED:_
2918 `gjdoc' also allows you to explicitly delineate the first sentence
2919 by putting it in a `<span>' tag with the CSS class `first-sentence'.
2922 * <span class="first-sentence">This. is. the. first.
2923 * sentence.</span> This is the second sentence.
2926 Note that this will only work with `gjdoc', but shouldn't hurt when
2927 using another documentation system since the `<span>' tag usually
2928 doesn't show up in the output.
2931 File: cp-tools.info, Node: Adding Custom Resources, Prev: First Sentence Detector, Up: Gjdoc Concepts
2933 6.5 Adding Images and Other Resources
2934 =====================================
2936 Sometimes you want to decorate your documentation with secondary
2937 resources such as images, SVG graphics, applets, and so on. To do so,
2938 simply put the required files in a subdirectory 'doc-files' in the
2939 package directory corresponding to the documentation entry you want to
2940 decorate, and refer to it with the URL `doc-files/FILENAME'.
2942 For example, if you want to add an image to the description of class
2943 `baz.FooBar', create a directory `doc-files' in the directory `baz'
2944 containing `FooBar.java' and put your file, say `diagram.png', into
2945 that directory. Then, add the HTML code like this to a comment in
2947 <img src="doc-files/diagram.png" width="200" height="150"
2950 This works because the `doc-files' subdirectories will be copied to
2951 the target documentation directory every time you generate the
2954 Note however that by default, the `doc-files' directory will not be
2955 copied deeply. In other words, if you create subdirectories under
2956 `doc-files' they will not be copied and any resources located in these
2957 subdirectories will not be accessible in your generated documentation.
2958 You can specify option `-docfilessubdirs' to remove this limitation.
2960 Sometimes you want to use option `-docfilessubdirs', but there are
2961 certain directories which you don't want to be copied, for example
2962 because they contain source files for the resources in `doc-files'.
2963 For cases like this, use `-excludedocfilessubdir' to specify
2964 directories to be omitted.
2967 File: cp-tools.info, Node: I18N Issues, Prev: Other Tools, Up: Top
2972 Some tools -*note Security Tools::- allow using other than the English
2973 language when prompting the User for input, and outputting messages.
2974 This chapter describes the elements used to offer this support and how
2975 they can be adapted for use with specific languages.
2979 * Language Resources:: Where resources are located
2980 * Message Formats:: How messages are internationalized
2983 File: cp-tools.info, Node: Language Resources, Next: Message Formats, Prev: I18N Issues, Up: I18N Issues
2985 7.1 Language-specific resources
2986 ===============================
2988 The Tools use Java `ResourceBundle's to store messages, and message
2989 templates they use at runtime to generate the message text itself,
2990 depending on the locale in use at the time.
2992 The Resource Bundles these tools use are essentially Java Properties
2993 files consisting of a set of Name/Value pairs. The Name is the Property
2994 Name and the Value is a substitution string that is used when the code
2995 references the associated Name. For example the following is a line in
2996 a Resource Bundle used by the `keytool' Tool:
2998 Command.23=A correct key password MUST be provided
3000 When the tool needs to signal a mandatory but missing key password,
3001 it would reference the property named `Command.23' and the message "`A
3002 correct key password MUST be provided'" will be used instead. This
3003 indirect referencing of "resources" permits replacing, as late as
3004 possible, the English strings with strings in other languages, provided
3005 of course Resource Bundles in those languages are provided.
3007 For the GNU Classpath Tools described in this Guide, the Resource
3008 Bundles are files named `messages[_ll[_CC[_VV]]].properties' where:
3011 Is the 2-letter code for the Language,
3014 Is the 2-letter code for the Region, and
3017 Is the 2-letter code for the Variant of the language.
3019 The complete list of language codes can be found at Code for the
3020 representation of names of languages
3021 (http://ftp.ics.uci.edu/pub/ietf/http/related/iso639.txt). A similar
3022 list for the region codes can be found at ISO 3166 Codes (Countries)
3023 (http://userpage.chemie.fu-berlin.de/diverse/doc/ISO_3166.html).
3025 The location of the Resource Bundles for the GNU Classpath Tools is
3026 specific to each tool. The next table shows where these files are found
3027 in a standard GNU Classpath distribution:
3030 `gnu/classpath/tools/jarsigner'
3033 `gnu/classpath/tools/keytool'
3035 The collection of Resource Bundles in a location act as an inverted
3036 tree with a parent-child relationship. For example suppose in the
3037 `gnu/classpath/tools/keytool' there are 3 message bundles named:
3039 1. `messages.properties'
3041 2. `messages_fr.properties'
3043 3. `messages_fr_FR.properties'
3045 In the above example, bundle #1 will act as the parent of bundle #2,
3046 which in turn will act as the parent for bundle #3. This ordering is
3047 used by the Java runtime to choose which file to load based on the set
3048 Locale. For example if the Locale is `fr_CH', `messages_fr.properties'
3049 will be used because (a) `messages_fr_CH.properties' does not exist,
3050 but (b) `messages_fr.properties' is the parent for the required bundle,
3051 and it exists. As another example, suppose the Locale was set to
3052 `en_AU'; then the tool will end up using `messages.properties' because
3053 (a) `messages_en_AU.properties' does not exist, (b)
3054 `messages_en.properties' which is the parent for the required bundle
3055 does not exist, but (c) `messages.properties' exists and is the root of
3058 You can see from the examples above that `messages.properties' is
3059 the safety net that the Java runtime falls back to when failing to find
3060 a specific bundle and its parent(s). This file is always provided with
3061 the Tool. In time, more localized versions will be included to cater
3062 for other languages.
3064 In the meantime, if you are willing to contribute localized versions
3065 of these resources, grab the `messages.properties' for a specific tool;
3066 translate it; save it with the appropriate language and region suffix
3067 and mail it to `classpath@gnu.org'.
3070 File: cp-tools.info, Node: Message Formats, Prev: Language Resources, Up: I18N Issues
3075 If you open any of the `messages.properties' described in the previous
3076 section, you may see properties that look like so:
3078 Command.67=Issuer: {0}
3079 Command.68=Serial number: {0,number}
3080 Command.69=Valid from: {0,date,full} - {0,time,full}
3081 Command.70=\ \ \ \ \ until: {0,date,full} - {0,time,full}
3083 These are Message Formats used by the tools to customize a text
3084 string that will then be used either as a prompt for User input or as
3087 If you are translating a `messages.properties' be careful not to
3088 alter text between curly braces.
3094 Node: Applet Tools
\7f6146
3095 Node: appletviewer Tool
\7f6719
3096 Node: gcjwebplugin
\7f9834
3097 Node: Security Tools
\7f10146
3098 Node: jarsigner Tool
\7f10799
3099 Node: Common jarsigner Options
\7f11847
3100 Node: Signing Options
\7f13162
3101 Node: Verification Options
\7f15745
3102 Node: keytool Tool
\7f16333
3103 Node: Getting Help
\7f20761
3104 Node: Common keytool Options
\7f21505
3107 Ref: keysize
\7f22390
3108 Ref: validity
\7f22655
3109 Ref: storetype
\7f22870
3110 Ref: storepass
\7f23201
3111 Ref: keystore
\7f23398
3112 Ref: provider
\7f23941
3114 Ref: verbose
\7f24819
3115 Node: Distinguished Names
\7f24911
3117 Node: Add/Update Commands
\7f26168
3118 Node: Command -genkey
\7f26696
3119 Node: Command -import
\7f29105
3120 Node: Command -selfcert
\7f32249
3121 Node: Command -cacert
\7f34428
3122 Node: Command -identitydb
\7f35481
3123 Node: Export Commands
\7f36139
3124 Node: Command -certreq
\7f36455
3125 Node: Command -export
\7f38861
3126 Node: Display Commands
\7f40058
3127 Node: Command -list
\7f40390
3128 Node: Command -printcert
\7f41523
3129 Node: Management Commands
\7f41907
3130 Node: Command -keyclone
\7f42339
3131 Node: Command -storepasswd
\7f43742
3132 Node: Command -keypasswd
\7f44471
3133 Node: Command -delete
\7f45665
3134 Node: Other Tools
\7f46288
3135 Node: jar Tool
\7f47130
3136 Node: javah Tool
\7f48522
3137 Node: gcjh Tool
\7f49741
3138 Node: native2ascii Tool
\7f50854
3139 Node: orbd Tool
\7f51315
3140 Node: serialver Tool
\7f52045
3141 Node: rmid Tool
\7f52514
3142 Node: rmiregistry Tool
\7f53455
3143 Node: tnameserv Tool
\7f54295
3144 Node: gjdoc Tool
\7f54919
3145 Node: Invoking the Standard Doclet
\7f56907
3146 Node: Option Summary by Type
\7f58062
3147 Node: Source Set Options
\7f60517
3148 Node: Source Format Options
\7f62381
3149 Node: Interlinking Options
\7f63895
3150 Node: Generation Options
\7f66672
3151 Node: Taglet Options
\7f72769
3152 Node: Doclet Options
\7f74990
3153 Node: Decoration Options
\7f76566
3154 Node: Output Control Options
\7f80657
3155 Node: Verbosity Options
\7f84189
3156 Node: Virtual Machine Options
\7f84535
3157 Node: Invoking a Custom Doclet
\7f85931
3158 Node: Gjdoc Option Summary
\7f86606
3159 Node: Other Doclets
\7f86786
3160 Node: Built-in Doclets
\7f87014
3161 Node: Using TexiDoclet
\7f87269
3162 Node: Using XmlDoclet
\7f87491
3163 Node: Using IspellDoclet
\7f87716
3164 Node: Using DebugDoclet
\7f87944
3165 Node: Third-party Doclets
\7f88144
3166 Node: DocBook Doclet
\7f88360
3167 Node: PDFDoclet
\7f88503
3168 Node: JUnitDoclet
\7f88656
3169 Node: Gjdoc Concepts
\7f88790
3170 Node: Taglets
\7f89034
3171 Node: Writing Doclets
\7f89217
3172 Node: Doclet Invocation Interface
\7f89557
3173 Node: Using AbstractDoclet
\7f90349
3174 Node: GNU Doclet SPI
\7f93343
3175 Node: XHTML Fragments
\7f94815
3176 Node: First Sentence Detector
\7f96248
3177 Node: Adding Custom Resources
\7f98010
3178 Node: I18N Issues
\7f99706
3179 Node: Language Resources
\7f100208
3180 Node: Message Formats
\7f103872
projects / platform / upstream / gcc48.git / blob