From 4777ec26fdd43c6903f5b081327481335fbf2404 Mon Sep 17 00:00:00 2001 From: Diomidis Spinellis Date: Fri, 28 Sep 2007 12:44:56 +0000 Subject: [PATCH] Add installation instructions and clarify invocation. --- doc/cd-oper.xml | 94 ++++++++++++++++++++++++++++++++----------------- doc/index.xml | 1 + doc/install.xml | 38 ++++++++++++++++++++ doc/ver.xml | 3 ++ 4 files changed, 103 insertions(+), 33 deletions(-) create mode 100644 doc/install.xml diff --git a/doc/cd-oper.xml b/doc/cd-oper.xml index 167a0f8..6f2811c 100644 --- a/doc/cd-oper.xml +++ b/doc/cd-oper.xml @@ -1,13 +1,6 @@ -To use UMLGraph class drawing facility you need to have -javadoc -and -Graphviz -installed on your computer. -Both programs are freely available, from Sun and AT&T respectively, -for many platforms including Unix and Windows. UMLGraph's input follows the Java syntax and semantics. However, since the main purpose of UMLGraph is the declarative specification of @@ -23,21 +16,55 @@ Java code. Note however that UMLGraph was not originally designed for this purpose; the resulting graphs may be large and unwieldy.

-UMLGraph is implemented as a javadoc doclet (a program satisfying the -doclet API that specifies the content and format of the output -generated by the javadoc tool). -Javadoc is part of the Sun JDK, so a typical JDK installation will also -include javadoc. -Before running javadoc you need to place the UmlGraph.jar +There are various ways to invoke UmlGraph, +each providing a different balance between convenience and flexibility. +

Option 1: Using the Supplied Scipt

+This is the simplest option. +If umlgraph (or umlgraph.bat) 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: + +umlgraph Test png + +Any additional UmlGraph or javadoc 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). +

Option 2: Running Java

+This option provides the maximum flexibility. +In order to run, javadoc needs to access tools.jar. +You can accomplish this in two ways. +
    +
  1. +Specify the location of tools.jar 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 + +java -classpath "lib/UmlGraph.jar;c:\program files\java\jdk1.6.0_02\lib\Tools.jar" + gr.spinellis.umlgraph.doclet.UmlGraph -package Test.java + +and under Unix + +java -classpath '/usr/share/lib/UmlGraph.jar:/opt/Java-1.6/lib/tools.jar' \ +gr.spinellis.umlgraph.doclet.UmlGraph -package Test.java + +
    2. +
  2. Place the UmlGraph.jar file in a directory that also contains the Java SDK tools.jar file. -You can accomplish this either by copying UmlGraph.jar to the SDK +You can accomplish this either by copying UmlGraph.jar to the SDK lib directory where tools.jar resides, or by copying the JDK tools.jar file into the directory -where you install UmlGraph. +where you installed UmlGraph. You then run java -jar /path/to/UmlGraph.jar yourfile1.java ... +
    3. +
You can use any of the javadoc general options; -private is usually needed to avoid having to explicitly specify public elements. @@ -53,10 +80,27 @@ 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.

+ +

Option 3: Running Javadoc

+Alternatively, you can also run UMLGraph from within javadoc. +This can be useful if your IDE provides additional support for running javadoc. +In this case you run +javadoc with arguments -doclet gr.spinellis.umlgraph.doclet.UmlGraph +-docletpath /path/to/UmlGraph.jar +and append at the end the file(s) that contain your diagram +specification. +Example: + +javadoc -docletpath UmlGraph.jar -doclet gr.spinellis.umlgraph.doclet.UmlGraph -private Simple.java + + +

Running Dot

+The last two options, will generate the UML diagram in +Graphviz dot format. +This is a text file that can be processed by the Graphviz dot +program to layout and draw the graph. javadoc will create by default a file named graph.dot in the current directory. -This is a text file that can be processed by the Graphviz - dot program to layout and draw the graph. A command line like the following will convert the graph.dot file into Postscript: @@ -73,22 +117,6 @@ You also can pipe the result of UMLGraph directly into dot: java -jar /.../UmlGraph.jar -private -output - Simple.java | dot -Tgif -ograph.gif -In the bin directory of the UMLGraph distribution you will -find a Unix shell script and a Microsoft Windows batch file that you can -customize to invoke UmlGraph and dot through a single command. - -

-Alternatively, you can also run UMLGraph from within javadoc. -This can be useful if your IDE provides additional support for running javadoc. -In this case you run -javadoc with arguments -doclet gr.spinellis.umlgraph.doclet.UmlGraph --docletpath /path/to/UmlGraph.jar -and append at the end the file(s) that contain your diagram -specification. -Example: - -javadoc -docletpath UmlGraph.jar -doclet gr.spinellis.umlgraph.doclet.UmlGraph -private Simple.java -

Note that when you use dot for generating SVG diagrams your should specify the -outputencoding UTF-8 option to UMLGraph. diff --git a/doc/index.xml b/doc/index.xml index eeae3f0..799150f 100644 --- a/doc/index.xml +++ b/doc/index.xml @@ -2,6 +2,7 @@ Introductionintro +Installationinstall Class Diagramscd-intro Class Diagram Operationscd-oper Class Modellingcd-model diff --git a/doc/install.xml b/doc/install.xml new file mode 100644 index 0000000..87bfed7 --- /dev/null +++ b/doc/install.xml @@ -0,0 +1,38 @@ + + + +To install UmlGraph follow these steps. +

    +
  1. Copy the files in lib to a directory you will +use for storing UmlGraph's installation +(for instance, /usr/local/lib). +
    2. +
  2. Copy the file bin/umlgraph (for Unix) or +bin/umlgraph.bat (for Windows) to a directory +of your execution path (for instance, /usr/local/bin).
    3. +
  3. Adjust the above file, setting UMLGRAPH_HOME to +point to the directory where you installed the UmlGraph library files. +
    4. +
+

+UMLGraph is implemented as a javadoc doclet (a program satisfying the +doclet API that specifies the content and format of the output +generated by the javadoc tool). +Furthermore, the output of UmlGraph needs to be post-processed +with the Graphviz dot program. +Therefore, to draw class diagrams with UmlGraph class you will need to have +javadoc +and +Graphviz +installed on your computer. +Both programs are freely available, from Sun and AT&T respectively, +for many platforms including Unix and Windows. +Javadoc is part of the Sun JDK, so a typical JDK installation will also +include javadoc. +

+

+To draw UML sequence diagrams you must also install the free +GNU plotutils +system. +

+ diff --git a/doc/ver.xml b/doc/ver.xml index 5a59ade..f39bf35 100644 --- a/doc/ver.xml +++ b/doc/ver.xml @@ -5,6 +5,9 @@
Version 4.9 Under development