SCons/Tool/javah.xml

   1 <?xml version="1.0"?>
   2 <!--
   3 SPDX-FileCopyrightText: Copyright The SCons Foundation (https://scons.org)
   4 SPDX-License-Identifier: MIT
   5 SPDX-FileType: DOCUMENTATION
   6
   7 This file is processed by the bin/SConsDoc.py module.
   8 -->
   9
  10 <!DOCTYPE sconsdoc [
  11 <!ENTITY % scons SYSTEM '../../doc/scons.mod'>
  12 %scons;
  13 <!ENTITY % builders-mod SYSTEM '../../doc/generated/builders.mod'>
  14 %builders-mod;
  15 <!ENTITY % functions-mod SYSTEM '../../doc/generated/functions.mod'>
  16 %functions-mod;
  17 <!ENTITY % tools-mod SYSTEM '../../doc/generated/tools.mod'>
  18 %tools-mod;
  19 <!ENTITY % variables-mod SYSTEM '../../doc/generated/variables.mod'>
  20 %variables-mod;
  21 ]>
  22
  23 <sconsdoc xmlns="http://www.scons.org/dbxsd/v1.0"
  24           xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  25           xsi:schemaLocation="http://www.scons.org/dbxsd/v1.0 http://www.scons.org/dbxsd/v1.0/scons.xsd">
  26
  27 <tool name="javah">
  28 <summary>
  29 <para>
  30 Sets construction variables for the &javah; tool.
  31 </para>
  32 </summary>
  33 <sets>
  34 <item>JAVAH</item>
  35 <item>JAVAHFLAGS</item>
  36 <item>JAVAHCOM</item>
  37 <item>JAVACLASSSUFFIX</item>
  38 </sets>
  39 <uses>
  40 <item>JAVAHCOMSTR</item>
  41 <item>JAVACLASSPATH</item>
  42 </uses>
  43 </tool>
  44
  45 <builder name="JavaH">
  46 <summary>
  47 <para>
  48 Builds C header and source files for
  49 implementing Java native methods.
  50 The target can be either a directory
  51 in which the header files will be written,
  52 or a header file name which
  53 will contain all of the definitions.
  54 The source can be the names of <filename>.class</filename> files,
  55 the names of <filename>.java</filename> files
  56 to be compiled into <filename>.class</filename> files
  57 by calling the &b-link-Java; builder method,
  58 or the objects returned from the
  59 &b-Java;
  60 builder method.
  61 </para>
  62
  63 <para>
  64 If the construction variable
  65 &cv-link-JAVACLASSDIR;
  66 is set, either in the environment
  67 or in the call to the
  68 &b-JavaH;
  69 builder method itself,
  70 then the value of the variable
  71 will be stripped from the
  72 beginning of any <filename>.class</filename> file names.
  73 </para>
  74
  75 <para>
  76 Examples:
  77 </para>
  78
  79 <example_commands>
  80 # builds java_native.h
  81 classes = env.Java(target="classdir", source="src")
  82 env.JavaH(target="java_native.h", source=classes)
  83
  84 # builds include/package_foo.h and include/package_bar.h
  85 env.JavaH(target="include", source=["package/foo.class", "package/bar.class"])
  86
  87 # builds export/foo.h and export/bar.h
  88 env.JavaH(
  89     target="export",
  90     source=["classes/foo.class", "classes/bar.class"],
  91     JAVACLASSDIR="classes",
  92 )
  93 </example_commands>
  94
  95 <note>
  96 <para>
  97 Java versions starting with 10.0 no longer use the
  98 <command>javah</command> command for generating JNI
  99 headers/sources, and indeed have removed the command entirely
 100 (see Java Enhancement Proposal
 101 <ulink url="https:openjdk.java.net/jeps/313">JEP 313</ulink>),
 102 making this tool harder to use for that purpose.
 103 &SCons; may autodiscover a <command>javah</command>
 104 belonging to an older release if there are multiple Java
 105 versions on the system, which will lead to incorrect results.
 106 To use with a newer Java, override the default values of &cv-link-JAVAH;
 107 (to contain the path to the <command>javac</command>)
 108 and &cv-link-JAVAHFLAGS; (to contain at least a <option>-h</option>
 109 flag) and note that generating headers with
 110 <command>javac</command> requires supplying source
 111 <filename>.java</filename> files only,
 112 not <filename>.class</filename> files.
 113 </para>
 114 </note>
 115 </summary>
 116 </builder>
 117
 118 <cvar name="JAVAH">
 119 <summary>
 120 <para>
 121 The Java generator for C header and stub files.
 122 </para>
 123 </summary>
 124 </cvar>
 125
 126 <cvar name="JAVAHCOM">
 127 <summary>
 128 <para>
 129 The command line used to generate C header and stub files
 130 from Java classes.
 131 Any options specified in the &cv-link-JAVAHFLAGS; construction variable
 132 are included on this command line.
 133 </para>
 134 </summary>
 135 </cvar>
 136
 137 <cvar name="JAVAHCOMSTR">
 138 <summary>
 139 <para>
 140 The string displayed when C header and stub files
 141 are generated from Java classes.
 142 If this is not set, then &cv-link-JAVAHCOM; (the command line) is displayed.
 143 </para>
 144
 145 <example_commands>
 146 env = Environment(JAVAHCOMSTR="Generating header/stub file(s) $TARGETS from $SOURCES")
 147 </example_commands>
 148 </summary>
 149 </cvar>
 150
 151 <cvar name="JAVAHFLAGS">
 152 <summary>
 153 <para>
 154 General options passed to the C header and stub file generator
 155 for Java classes.
 156 </para>
 157 </summary>
 158 </cvar>
 159
 160 </sconsdoc>