From: Svjatoslav Agejenko Date: Thu, 19 Dec 2024 21:48:28 +0000 (+0200) Subject: Move CLI usage documentation into separate file X-Git-Url: http://www2.svjatoslav.eu/gitweb/?a=commitdiff_plain;h=98d4483346a44b237212ddae1d25fc680f0715a3;p=javainspect.git Move CLI usage documentation into separate file --- diff --git a/.gitignore b/.gitignore index 1d3a572..510086b 100755 --- a/.gitignore +++ b/.gitignore @@ -8,4 +8,5 @@ dependency-reduced-pom.xml /*.iml /JavaInspect.dot /JavaInspect.svg -/doc/index.html \ No newline at end of file +/doc/index.html +/doc/usage\ cli.html diff --git a/doc/index.org b/doc/index.org index 12fe08a..7e8838a 100644 --- a/doc/index.org +++ b/doc/index.org @@ -59,7 +59,10 @@ To use JavaInspect as a commandline tool, JavaInspect source repository has to be cloned locally. See: [[id:c47ff9a6-d737-4b73-9393-1c63d2ca1101][Getting the source code]]. Then study and execute installation script: -: commandline launcher/install +#+begin_src sh + cd commandline\ launcher + ./install +#+end_src After installation, new commandline tool should be available : javainspect @@ -71,86 +74,10 @@ Quick commandline usage help can be viewed by issuing :PROPERTIES: :ID: 2ad2889e-6c95-4662-b3f4-2c341fc74522 :END: -JavaInspect can be controlled in 2 different ways: +JavaInspect utility can be used in 2 different ways: + [[id:acf1896a-74b4-4914-acf6-a77075e07f25][as standalone commandline utility]] + [[id:bbeeffc8-3767-440d-8d93-ec9124dd60ee][as embedded Java library via Java API]] -** Usage as commandline utility - :PROPERTIES: - :ID: acf1896a-74b4-4914-acf6-a77075e07f25 - :END: -*** Available commandline arguments -#+BEGIN_VERSE --j (existing files)... - JAR file(s) to render. - --c (existing directories)... - Classpath directories - --n (string) - Graph name. (default: "graph") - ---debug - Show debug info. - --h, --help - Show commandline usage help. - --k - Keep dot file. - --ho - Hide orphaned classes. - --w (one to many strings)... - Whitelist glob(s). - --b (one to many strings)... - Blacklist glob(s). - --r (one to many strings)... - root class(es). - --d (existing directory) - Target directory. Default is current directory. - --t (options: png, svg) - Target image type. Default is: svg. -#+END_VERSE -*** Specifying classes to render -Normal Java application has immense complexity. In addition to code -that was directly written by particular project developers, lots of -functionality is typically added as frameworks or libraries to the -project. In addition there is significant Java standard library. - -Because JavaInspect uses reflection, it does not easily distinguish -between those. In normal situation you would rather want to visualize -only code that was developed specifically for your project and leave -frameworks like Spring etc. out. If you visualize all classes that are -possibly reachable from you project, you will easily get huge and -incomprehensible graph. - -JavaInspect can digest compiled Java classes in 2 modes: -1. Provide list of Jar files. Use *-j* option. -2. Provide list of filesystem directories that can be used as - classpath root. Use *-c* option. - -Currently JavaInspect uses following algorithm to add classes to -rendered graph: - -- All classes that were found in Jar files are added to graph by default. -- None of the classes that were found in filesystem directories are - added to the graph by default (unless explicitly referenced). (TODO: - for consistency it would be better to add them too by default) -- If whitelist is specified (*-w* option) everything that is not - matched by whitelist pattern(s) will be removed from the graph. -- If blacklist is specified (*-b* option) everything that is matched - by blacklist pattern(s) will be removed from the graph. -- Root classes can be specified using *-r* option. Root classes will - be added to the graph. JavaInspect will then try to recursively - discover all classes that were referenced by root class and add - those also to the graph. - ** Usage via Java API :PROPERTIES: :ID: bbeeffc8-3767-440d-8d93-ec9124dd60ee @@ -363,4 +290,4 @@ License, or (at your option) any later version. - [[https://www2.svjatoslav.eu/gitweb/?p=javainspect.git;a=summary][Browse Git repository online]] - [[https://www2.svjatoslav.eu/gitweb/?p=javainspect.git;a=snapshot;h=HEAD;sf=tgz][Download latest snapshot in TAR GZ format]] - You can clone Git repository using git: - : git clone https://www2.svjatoslav.eu/git/javainspect.git + : git clone https://www3.svjatoslav.eu/git/javainspect.git diff --git a/doc/usage cli.org b/doc/usage cli.org new file mode 100644 index 0000000..520ec79 --- /dev/null +++ b/doc/usage cli.org @@ -0,0 +1,102 @@ +:PROPERTIES: +:ID: acf1896a-74b4-4914-acf6-a77075e07f25 +:END: + +#+TITLE: JavaInspect - usage from commandline +#+LANGUAGE: en +#+LATEX_HEADER: \usepackage[margin=1.0in]{geometry} +#+LATEX_HEADER: \usepackage{parskip} +#+LATEX_HEADER: \usepackage[none]{hyphenat} + +#+OPTIONS: H:20 num:20 +#+OPTIONS: author:nil + + +* Available commandline arguments + + +- -j (existing files)... :: JAR file(s) to render. + +- -c (existing directories)... :: Classpath directories + +- -n (string) :: Graph name. (default: "graph") + +- --debug :: Show debug info. + +- -h, --help :: Show commandline usage help. + +- -k :: Keep dot file. + +- -ho :: + Hide orphaned classes. + +- -w (one to many strings)... :: Whitelist glob(s). + +- -b (one to many strings)... :: Blacklist glob(s). + +- -r (one to many strings)... :: root class(es). + +- -d (existing directory) :: Target directory. Default is current directory. + +- -t (options: png, svg) :: Target image type. Default is: svg. + +* Specifying classes to render + +Normal Java application has immense complexity. In addition to code +that was directly written by particular project developers, lots of +functionality is typically added as frameworks or libraries to the +project. In addition there is significant Java standard library. + +Because JavaInspect uses reflection, it does not easily distinguish +between those. In normal situation you would rather want to visualize +only code that was developed specifically for your project and leave +frameworks like Spring etc. out. If you visualize all classes that are +possibly reachable from you project, you will easily get huge and +incomprehensible graph. + +JavaInspect can digest compiled Java classes in 2 modes: +1. Provide list of Jar files. Use *-j* option. +2. Provide list of filesystem directories that can be used as + classpath root. Use *-c* option. + +Currently JavaInspect uses following algorithm to add classes to +rendered graph: + +- All classes that were found in Jar files are added to graph by default. +- None of the classes that were found in filesystem directories are + added to the graph by default (unless explicitly referenced). (TODO: + for consistency it would be better to add them too by default) +- If whitelist is specified (*-w* option) everything that is not + matched by whitelist pattern(s) will be removed from the graph. +- If blacklist is specified (*-b* option) everything that is matched + by blacklist pattern(s) will be removed from the graph. +- Root classes can be specified using *-r* option. Root classes will + be added to the graph. JavaInspect will then try to recursively + discover all classes that were referenced by root class and add + those also to the graph. + +* Examples + +Visualize java Jar file. All classes. Hide orphaned classes: + +#+begin_src sh + javainspect \ + -j target/sixth-3d-*-SNAPSHOT.jar \ + -d doc/graphs/ \ + -n "all classes" \ + -t png -ho +#+end_src + + +Visualize java Jar file. All classes. Hide orphaned classes. Apply +whitelist: + +#+begin_src sh + javainspect \ + -j target/sixth-3d-*-SNAPSHOT.jar \ + -d doc/graphs/ \ + -n "GUI" \ + -t png \ + -w "eu.svjatoslav.sixth.e3d.gui.*" \ + -ho +#+end_src diff --git a/tools/update web site b/tools/update web site index 47cc645..6445b75 100755 --- a/tools/update web site +++ b/tools/update web site @@ -8,6 +8,9 @@ cd "${0%/*}"; if [ "$1" != "T" ]; then gnome-terminal -- "$0" T; exit; fi rm -f index.html emacs --batch -l ~/.emacs --visit=index.org --funcall=org-html-export-to-html --kill + rm -f usage\ cli.html + emacs --batch -l ~/.emacs --visit=usage\ cli.org --funcall=org-html-export-to-html --kill + # Upload project homepage to the server. rsync -avz --delete -e 'ssh -p 10006' ./ \ --include="*/" \