CXXWRAP(1) CXXWRAP(1) NAME cxxwrap - wrap C++ files in Java and produce documentation SYNOPSIS cxxwrap [--root=path] [--files=namefile] [--jni] [--class- path=path] [--jni-makefile=file] [--jni-pack- ages=pkg[,pkg2...]] [--jni-import-hook=file] [--jni-begin- hook=file] [--jni-end-hook=file] [--jni-callbacks] [--jni- attributes] [--jni-operators] [--jni-expand-defaults] [--write-cache=file] [--read-cache=file] [--cache-com- ments] [--template-package=[parameter|invoking|auto] [--package-prefix=path] [--man] [--manpath=path] [--html] [--htmlpath=path] [--html-autolink] [--html-printable] [--public-doc] [--analyze=file] [--depend=file] [--ver- bose] [--trace] [--help] [file ...] DESCRIPTION cxxwrap reads some C++ header files which define a set of classes to be documented and/or wrapped in Java. Output filters for HTML documentation, manual page documentation, and Sun's Java JNI (Java to Native Interface) wrappers for Java are provided. cxxwrap also provides a simple analy- sis package which computes statistical data about the API being wrapped or documented. OPTIONS --root=path Read all subsequent headers from directories under path. For example, specifying "--root=foo bar/baz.h" is equivalent to specifying "foo/bar/baz.h", except that the package of the class "baz" (defined in "baz.h") will be "bar", not "foo/bar". Files with absolute pathnames are unaf- fected by the value of path. This feature is use- ful if you have a large file of relative pathnames, which you want cxxwrap to read from another direc- tory, and the directory prefix is not relevant to the Java package assignments or to the C++ documen- tation's listing of the header file to include for these classes. (Also see the --package-prefix option for a way to add extra package prefix onto each class's package assignment.) --files=file Read file to get the names of all header files to scan (instead of listing them on the command line). It is useful when there are too many classes in the library and the command line becomes too unwieldy for your shell. Note that any --root option will still be in effect (the filenames read from file are relative paths, just as if they had been entered on the command line). --jni Generate Java JNI wrappers, which consist of C++ sources for the native part, and Java sources for the Java part of the JNI interface. After running this you will need to compile both the C++ and Java sources. (See below for more details about how the Java code is generated.) --classpath=path Use path as the path to write the Java and C++ JNI files. Note that the Java package name will deter- mine the actual target subdirectory under path. For each class C, cxxwrap writes files C_jni.cxx and C.java files under path. (This option is only useful if --jni is also specified.) --jni-makefile=file Write a definition of the make symbol JNIOBJ to the file file. This can help in writing makefiles for building JNI shared libraries. The definition will include all object files (assumed to be formed by substituting .o for .cxx in the C++ source file- name). --jni-packages=pkg[,pkg2...] Only emit JNI definitions for classes in the speci- fied packages. This is of value if you have previ- ously wrapped one or more C++ libraries, and are adding more wrappers at a later date. You still need to parse the original headers (or read them from cache, see the --read-cache option), but you do not need to emit any JNI code for them. --jni-import-hook=file Specify some Java code which will be inserted in every generated Java file for the JNI implementa- tion, immediately after the import statements. The code is read from file. This can be used with --jni-begin-hook and --jni-end-hook to put coding hooks into the JNI Java code. For example if you wish to monitor entry into native code for the pur- poses of guarding unthreadsafe native code with a locking mechanism. --jni-begin-hook=file Specify some Java code which will be inserted in every generated Java file for the JNI implementa- tion, at the beginning of the method and prior to any native method invocations. The code is read from file. If the comment of a method contains the string , then the hooks (begin and end) are not incuded for that method. --jni-end-hook=file Specify some Java code which will be inserted in every generated Java file for the JNI implementa- tion, at the end of the method and after to any native method invocations. The code is read from file. If the comment of a method contains the string , then the hooks (begin and end) are not incuded for that method. --jni-callbacks Specify that generic C++ callback interfaces gets wrapped as a Java interface. The recognized pat- tern is typedef void(*callback_func)(int i, Example- Data* ed, void* userdata); void registerCallback(void* userdata, call- back_func cbfunc); This code will be wrapped into a Java interface specification and a method which accepts objects implementing thie interface: public interface callback_funcCallback { public void callback_func(int i, Example- Data ed); } and public void registerCallback(callback_funcCall- back cbfunc) { ... } --jni-attributes Specify that C++ public attributes should have accessor methods generated automatically. --jni-operators Specify that C++ operator overloads should be wrapped in Java. This is done by replacing the operator name with an text equivalent, e.g. "oper- ator +=" becomes "AddEq". --jni-expand-defaults Expand C++ methods with default values of parame- ters into multiple methods in Java which have no default parameters. This allows a crude Java approximation of the C++ facility for matching var- ious methods signatures. --write-cache=file After all other processing is complete, cache the currently known class definitions to file. The format of the cache is dependent on the exact ver- sion of cxxwrap (it is not expected to be main- tained across versions). This option can be used to capture class definitions for later JNI wrap- ping, especially for template definitions and expansions. Only one instance of this option can be used (the last one given will be honored). --read-cache=file Read file to preload a number of previously known class definitions. Any number of instances of this option may be used. --cache-comments Include comments in the cache (see --read-cache and --write-cache options). Normally, cxxwrap does not include comments in the cache, meaning that the documentation for the cached classes is lost. New JNI wrappers (or wrappers for extended packages) may still be generated from the cache. Use this option to save space in the cache. --template-package=mode Specify a policy for deciding which package a C++ template instatiation belongs to. The available values of mode are invoking templates are instantiated in the package of the first class that invokes them. Since cxxwrap's order of operating on classes is somewhat arbitrary, this can lead to random placement of template definitions. parameter templates are instantiated in the package of the first object parameter. If no known object parameter is present, the invoking package is used. auto (default) search for package dependencies between the template source package and the parameters, and instantiate the template in the lowest common dependent package. --package-prefix=path Set a prefix for Java packages which are generated from C++ include paths. For example, you might want classes found in the header file "foo/classes.h" to be part of the package "org.foo- mania.dave.foo", so you would specify "--package- prefix=org.foomania.dave" to cxxwrap in order to accomplish this. You should only give this option once. The default is no prefix. --man Generate manual pages documenting each class. --manpath=path Use path as a path to the manual pages. The class pages will be installed under the man3 subdirectory in path. This directory will be created if it does not exist. --html Generate HTML pages documenting each class. --htmlpath=path Use path as a path to write the HTML files. All of the generated HTML, including an index file index.html, will be written to the path directory. The directory path will be created if it does not exist. --html-autolink Automatically link class name references to docu- mented definitions. Although Sun's javadoc does not do this, and the javadoc documentation web page claims it is morally wrong, it can be desirable for many C++ packages, the class names of which are typically distinguished from ordinary words by a prefix (e.g. package "Foo", class "Controller" is named "FooController"). --html-printable Generate simplified HTML which is suitable for printing with a HTML tool such as html2ps. This means using standard structured HTML instead of frames and tables, and not including hyperlinked navigation panels. --public-doc Do not document protected or private methods in HTML or man pages. --analyze=file Write an analysis of the toolkit API scanned to file. The analysis lists the number of classes, average class size (in terms of methods), and statistics related to the documentation of the classes. This is useful for measuring the progress of documentation projects, and may be useful for developing heuristics about what type of documenta- tion coverage and cross referencing is most effec- tive. --depend=file Write a report of class and package dependencies to file. --verbose Give play-by-play commentary on what cxxwrap is doing. --trace Echo all C++ tokens read from header files. This is used to debug the parser, and isn't particularly useful or even interesting otherwise. --help Print a short help screen summarizing the available options. CLASSES AND PACKAGES Since cxxwrap is designed to work with C++ and Java, it needs a scheme for assigning a Java package to a C++ class. The convention followed by cxxwrap is to use the C++ class's relative header file path as the package name. So, for example, if you tell cxxwrap to read the file "example/sub/MyClass.h", any classes discovered in this file are considered to belong to the "example.sub" pack- age. Note that many classes may be defined in a given header file, and the name of the header file need not match that of any of the classes defined within it. Of course, the JNI produced by cxxwrap must follow the java rules, which require the java file to match names with the class defined in the file. If C++ namespaces are used, the namespace is appended to the path derived by the rules above to arrive at the final package name. So, for example, if the header file "foo/a.h" defines class C in namespace "bar", the Java package will be "foo.bar", and class C's full name in Java will be "foo.bar.C". COMMENT PARSING Comments of three varieties are recognized by cxxwrap. The philosophy is to try and parse the widest variety of comments, so that large legacy code bases can be quickly documented without having to perform tedious comment updates. Standard C style comments beginning with /* and ending with */ are recognized. cxxwrap will ignore asterisks which begin comment lines, so that the comment style such as /* this is * the way some * folks like to * write comments. */ will work correctly (i.e. the asterisks will not be seen). cxxwrap also recognizes C++ style comments, which begin with // and go to the end of the line. C++ style comments may span several lines (each of which must begin with a // sequence). Within the body of a comment, references to known classes cause cxxwrap to use an HTML hyperlink so that the reader can look up the class API directly from the comment text. Comments are associated with the declaration immediately following them. Thus, the following comments will be assigned correctly by cxxwrap: // a function named foo int foo(); /* a method named bar */ int bar(); while the following comment is not going to work, since it comes after the declaration: int foobar(); // a method named foobar cxxwrap also recognizes javadoc style comments, which begin with /** and end with */, and uses the javadoc tags in them to add extra information to the API listing. For a complete description of javadoc comment tags, see the web page http://java.sun.com/products/jdk/javadoc/writing- doccomments.html on Sun's public web site. The following standard javadoc tags are recognized by cxxwrap: @param describe a method parameter. @return describe the return value of a method. @see generate a "see also" link. @author define the author of the current class or method.. @date define the date on which the current comment was last edited. @version define the version string of the current class or method. @deprecated deprecate an API. In addition to these tags, cxxwrap also recognizes two non-standard javadoc tags: @header add text to the "header" section of the class docu- mentation (this tag is only recognized for class comments). @package add text to the package summary for the current package. cxxwrap will also look for a file called "PackageSummary.html" in the include path for each package when generating documentation. This file is assumed to contain a description of what is in the package, and will be included in the package sum- mary part of the documentation. When javadoc style comments are used, cxxwrap assumes that the contents of the comment are in HTML format. Some spe- cial handling of angle brackets is done, so that comments which include simple '<' and '>' characters which are not part of an HTML tag can be used without HTML escape sequences in the comment text. This allows comments to be more readable as plain ASCII. Also, as a convenience, cxxwrap will ignore a line of asterisks which begin a com- ment, so that comments delimited by a row of asterisks may be used: /********************************************* * This is considered to be a javadoc comemnt, * and the first line of asterisks is ignored. */ Classes which are not intended to be part of the public API may be designated by including the string "<>" in the class comment. This will prevent cxxwrap from including the class's documentation as part of any generated documentation. JAVA CODE GENERATION cxxwrap generates Java code for all classes which are part of the public API. The java API mimics the C++ API, with the following rules and restrictions: pointers, references, and objects All of the java objects generated by cxxwrap corre- spond with a C++ pointer. There is no concept of local native objects allocated on the stack, rather conversions are used (and appropriate C++ copy con- structors may need to be supplied for this use) to allocate all java objects on the heap. An extra method "delete()" is present on all of the java classes generated by cxxwrap, which calls the destructor for the encapsulated pointer. (Note that if the destructor is protected or private, it will not appear in the java API.) template generation cxxwrap instantiates templates as needed. The java class name of the instatiated templates is gener- ated by splicing "Of" and "And" strings into the classname, so that a C++ "vector" type becomes "vectorOffoo" in java. (It can get really ugly really fast, but it works.) By default, template expansions occur within the package with the least possible dependencies (this can be changed using the --template-package option). One possible nega- tive consequence of improper template instatiation policy is that you might have a very common expan- sion, say, "vectorOfint", which many packages use, but the java API will be tied to some package that expanded it (because it was used in a method param- eter or return value). This could introduce a somewhat artificial dependency between the pack- ages. enumerations In C++, enumeration types can be used to define compile-time constants. cxxwrap presents public enumerations defined within the scope of a class as const static ints in java. virtual functions In java, all methods are virtual. This has some implications for the classes produced by cxxwrap from C++ classes, which may have non-virtual func- tions. Your C++ non-virtual functions must obey the same rules as they would if virtual -- such as the fact that they cannot override a method in the superclass with the same function signature, but different return value. If you break these rules, the java code produced will be faulty (and javac, the java compiler, will notify you with errors at compile time). arrays and strings cxxwrap can wrap arguments or return values which are pointers to arrays of primitive types. Due to the way that JNI operates, a java interface cannot guarantee that the JVM's memory used for the array actually overlays the C++ memory. So, methods such as void foo(int* x); will be wrapped to present a java interface which internally might copy data between the user buffer and the JVM buffer: public void foo(int[] x); Also note that if the method returns a pointer to a primitive type, there's no way for cxxwrap to determine how long the array is, so a default value of "1" is used. This probably isn't what you want, of course. Character strings are a special case. cxxwrap will represent "const char*" as a "UTF" string in JNI, which means that methods will be generated which can use java strings (java.lang.String) as argu- ments to and return values from methods. Methods returning "unsigned char*" will be treated as arrays of java.lang.byte data, just like "int *" is an array of java.lang.int data. JNI arguments cxxwrap allows you to wrap C++ methods which have arguments whose type is defined by JNI: JNIEnv* and jobject. The former is implied, meaning that the argument will not appear in the java method, while the second maps directly to a java.lang.Object. For example, the C++ method void foo(JNIEnv* env, jobject obj); will map to the java method public void foo(Object obj); Whenthe method is invoked, the env argument will be filled in with the JNI environment that is passed by the JVM to the native method. The obj argument will be passed directly to the C++ method as type jobject. C++ invoking Java cxxwrap provides a way for Java programs to invoke C++ implementations. Frequently, you also need to have the C++ implementation invoke Java. For exam- ple, you might want to extend one of the classes defined by cxxwrap in Java. cxxwrap provides a facility for doing so, by using abstract classes. When an abstract C++ class is wrapped in JNI, cxxwrap provides a default Java constructor which will produce an implementation whose pure virtual methods are "live" in Java -- they can be extended in Java and if a C++ class invokes them, the Java method will be called. At present, only pure virtual functions whose return value is void or primitive, and whose arguments are all non-array types will be treated this way. Additionally, any Java extension of the class must take care to implement all of the pure virtual methods. Although legal Java code results even if some implementations are left out, any code which called such a method would enter an infinite recur- sion across the JNI boundary, usually resulting in a core dump when memory is exhausted. HTML DOCUMENTATION GENERATION The following notes apply to the HTML documentation pro- duced by cxxwrap. Classes which are not processed by cxxwrap may still be shown in the HTML documentation of a class's hierarchy, but will be called out as not documented. C++ LIMITATIONS The following notes describe some general limitations in the cxxwrap C++ parser. The parser is very fast but does not implement the full set of C++ language features, and does not parse every bit of the C++ code it encounters. Do not use cxxwrap to verify C++ syntax! cxxwrap only recognizes single public inheritance (only one superclass). Private inheritance is ignored, and mul- tiple inheritance is treated as if only the first class given in the declaration is a superclass. Class export specifiers (needed on Microsoft platforms) are assumed to be represented by a single token (such as a #define macro) appearing before the class name and immedi- ately after the "class" keyword. These specifiers are ignored. For example, in the declaration class MY_EXPORT foo { ... }; the symbol MY_EXPORT will be ignored by cxxwrap. No C preprocessor macros are resolved by cxxwrap. SEE ALSO javac(1), javah(1), javadoc(1) http://java.sun.com/products/jdk/javadoc/writingdoccom- ments.html BUGS See the file "BUGS" in the distribution. AUTHOR cxxwrap was written by David Deaven (deaven@deaven.net). Java(tm) is a registered trademark of Sun Microsystems Inc. 1 June 2000 CXXWRAP(1)