mirror of https://github.com/dspinellis/UMLGraph
126 lines
5.0 KiB
XML
126 lines
5.0 KiB
XML
<?xml version="1.0" ?>
|
|
<!-- $Id$ -->
|
|
<notes>
|
|
UMLGraph's input follows the Java syntax and semantics.
|
|
However,
|
|
since the main purpose of UMLGraph is the declarative specification of
|
|
UML diagrams there is no need to flesh-out each class's methods,
|
|
to completely specify each class, or to specify package information.
|
|
You only specify the details you want to appear on the graph.
|
|
If you wish your (Java) implementation to evolve together with the
|
|
design feel free to include code or additional details.
|
|
You can hide these details from the UML diagram using the <em>javadoc</em>
|
|
<code>@hidden</code> tag applied to classes, methods, and fields.
|
|
In theory you can also use UMLGraph to reverse engineer existing
|
|
Java code.
|
|
Note however that UMLGraph was not originally designed for this purpose;
|
|
the resulting graphs may be large and unwieldy.
|
|
<p />
|
|
There are various ways to invoke UmlGraph,
|
|
each providing a different balance between convenience and flexibility.
|
|
<h2>Option 1: Using the Supplied Script</h2>
|
|
This is the simplest option.
|
|
If <code>umlgraph</code> (or <code>umlgraph.bat</code>) is correctly
|
|
installed,
|
|
you can run UmlGraph by simply specifying the basename of
|
|
the Java file containing the diagram specification and the file type of
|
|
the generated diagram (e.g. gif, ps, png, svg).
|
|
Example:
|
|
<fmtcode ext="sh">
|
|
umlgraph Test png
|
|
</fmtcode>
|
|
Any additional UmlGraph or <em>javadoc</em> arguments can be added at
|
|
the end of the command line.
|
|
This command will read the specification file (e.g. Test.java) and
|
|
generate directly a diagram of the appropriate type
|
|
(e.g. Test.png).
|
|
<h2>Option 2: Running Java</h2>
|
|
This option provides the maximum flexibility.
|
|
In order to run, <em>javadoc</em> needs to access <code>tools.jar</code>.
|
|
You can accomplish this in two ways.
|
|
<ol>
|
|
<li>
|
|
Specify the location of <code>tools.jar</code> as a part of Java's classpath
|
|
and specify the full name of the UmlGraph doclet as an argument to Java.
|
|
This is an invocation example under Windows
|
|
<fmtcode ext="bat">
|
|
java -classpath "lib/UmlGraph.jar;c:\program files\java\jdk1.6.0_02\lib\Tools.jar"
|
|
gr.spinellis.umlgraph.doclet.UmlGraph -package Test.java
|
|
</fmtcode>
|
|
and under Unix
|
|
<fmtcode ext="sh">
|
|
java -classpath '/usr/share/lib/UmlGraph.jar:/opt/Java-1.6/lib/tools.jar' \
|
|
gr.spinellis.umlgraph.doclet.UmlGraph -package Test.java
|
|
</fmtcode>
|
|
</li>
|
|
<li> Place the <code>UmlGraph.jar</code>
|
|
file in a directory that also contains the Java SDK <code>tools.jar</code> file.
|
|
You can accomplish this either by copying <code>UmlGraph.jar</code> to the SDK
|
|
<code>lib</code> directory where <code>tools.jar</code> resides,
|
|
or by copying the JDK <code>tools.jar</code> file into the directory
|
|
where you installed UmlGraph.
|
|
You then run
|
|
<fmtcode ext="sh">
|
|
java -jar /path/to/UmlGraph.jar yourfile1.java ...
|
|
</fmtcode>
|
|
</li>
|
|
</ol>
|
|
You can use any of the <em>javadoc</em> general options;
|
|
<code>-private</code> is usually needed to avoid having to explicitly
|
|
specify public elements.
|
|
Example:
|
|
<fmtcode ext="sh">
|
|
java -jar /usr/jvm/java-1.5.0/lib/UmlGraph.jar -private Simple.java
|
|
</fmtcode>
|
|
<p />
|
|
Specifying some packages before the list of source files will designate
|
|
those packages as <em>local</em>.
|
|
When you specify a package list,
|
|
the SVG output UmlGraph generates will contain
|
|
local hyperlinks for the local classes
|
|
and hyperlinks to the Sun Java API documentation for all other classes.
|
|
<p />
|
|
|
|
<h2>Option 3: Running Javadoc</h2>
|
|
Alternatively, you can also run <em>UMLGraph</em> from within <em>javadoc</em>.
|
|
This can be useful if your IDE provides additional support for running <em>javadoc</em>.
|
|
In this case you run
|
|
<em>javadoc</em> with arguments <code>-doclet gr.spinellis.umlgraph.doclet.UmlGraph</code>
|
|
<code>-docletpath /path/to/UmlGraph.jar</code>
|
|
and append at the end the file(s) that contain your diagram
|
|
specification.
|
|
Example:
|
|
<fmtcode ext="sh">
|
|
javadoc -docletpath UmlGraph.jar -doclet gr.spinellis.umlgraph.doclet.UmlGraph -private Simple.java
|
|
</fmtcode>
|
|
|
|
<h2>Running Dot</h2>
|
|
The last two options, will generate the UML diagram in
|
|
<em>Graphviz</em> <em>dot</em> format.
|
|
This is a text file that can be processed by the <em>Graphviz</em> <em>dot</em>
|
|
program to layout and draw the graph.
|
|
<em>javadoc</em> will create by default a file named <code>graph.dot</code>
|
|
in the current directory.
|
|
A command line like the following will convert the <code>graph.dot</code>
|
|
file into Postscript:
|
|
<fmtcode ext="sh">
|
|
dot -Tps -ograph.ps graph.dot
|
|
</fmtcode>
|
|
or PNG
|
|
<fmtcode ext="sh">
|
|
dot -Tpng -ograph.png graph.dot
|
|
</fmtcode>
|
|
Refer to the <em>dot</em> documentation for information on creating other file formats
|
|
or adjusting the UMLGraph output.
|
|
<p />
|
|
You also can pipe the result of <em>UMLGraph</em> directly into <em>dot</em>:
|
|
<fmtcode ext="sh">
|
|
java -jar /.../UmlGraph.jar -private -output - Simple.java | dot -Tgif -ograph.gif
|
|
</fmtcode>
|
|
<p />
|
|
Note that when you use <em>dot</em> for generating SVG diagrams your
|
|
should specify the <code>-outputencoding UTF-8</code> option to UMLGraph.
|
|
This option will correctly render the stereotype guillemot characters
|
|
in the <em>dot</em> output and the corresponding SVG file.
|
|
</notes>
|