ianmadlenya / flowgen Goto Github PK

FLOWGEN SOFTWARE PREREQUISITES:
=====

• Python3 
http://www.python.org/getit/

• PlantUML (already provided; NO need to install)
http://plantuml.sourceforge.net/

• LLVM-Clang 3.1 (or superior) 
http://clang.llvm.org/

• Clang-Python3 bindings (already provided+fixed some bugs; NO need to install)
https://github.com/kennytm/clang-cindex-python3


ACKNOWLEDGMENTS:
=====
Thanks to the PlantUML team, specially to Arnaud Roques; to cldoc’s developer, Jesse Van Den Kieboom; 
and to the big LLVM+Clang developer community. This tool would not be possible without them.


INSTALLATION:
=====

[FOR UNIX-LIKE SYSTEMS: MAC/LINUX]

- Install Python3 (if not present)

- Install LLVM+Clang 3.1 (or superior). 

For MAC, you may try using a package management solution such as MacPorts or Fink.
For Linux (type?), you may try using a package management solution such as…

LLVM+Clang pre-built binaries are available from
http://llvm.org/releases/download.html

After installation, the environment variable
$LD_LIBRARY_PATH=path_to_llvm/lib
pointing to the libraries should have been set, or it can be set manually.
That folder contains required library files such as "libclang.dylib". 

- Download Flowgen from GitHub.


[FOR WINDOWS]

- Install Python3 (does not seem to work with a portable version, needs a normal installation)

- Install LLVM+Clang 3.1 (or superior). 

Prebuilt binaries available (3.4 or superior) from
http://llvm.org/releases/download.html
Choose the option 'Add LLVM to system PATH for all users’

- Download Flowgen from GitHub.



CONFIGURING AND RUNNING FLOWGEN:
=====

There is an example in the folder EXAMPLE, with some C++ code. 

[FOR UNIX-LIKE SYSTEMS: MAC/LINUX]

The makefile is configured to either compile the sample program, by typing
> make a.out
or to run Flowgen and generate the documentation, by typing
> make flowdoc
The documentation is generated as .html files inside flowdoc/

Note: erase the folder flowdoc/ to regenerate completely the documentation.
Note: it may be necessary to adjust the variables FLOWGEN_DIR and CXX to run the makefile. 
Note: type ‘make’ to do both actions (compiling and generating documentation) in the same run.
Note [MAC SPECIFIC]: by default, makefiles are not recognized on Mac systems. In order to check, 
      you can do 'make --version'. If it says: ‘-bash: make: command not found’, then you should install it. 
      The easiest is to install the xCode addition to Mac OS X. 

The //$ annotations and the code can be changed in the test C++ code to experiment with Flowgen.

[FOR WINDOWS]

Set FLOWGEN_DIR environment variable to the FLOWGEN folder
The make batch file ‘make_WIN.bat’ is configured to run the example
The documentation is generated as .html files inside flowdoc/

NOTE: FOR THE MOMENT, the user has to copy manually the folder '/htmlCSSandJS' from the Flowgen folder
      into the /flowdoc folder of the documentation project
      This should be done automatically by make_WIN.bat

The //$ annotations and the code can be changed in the test C++ code to experiment with Flowgen.



MAP OF FILES
=====

build_db.py —> Flowgen Python3 executable
makeflows.py —> Flowgen Python3 executable
makehtml.py —> Flowgen Python3 executable
plantuml.jar —> PlantUML java executable, used by Flowgen
ToDoList.txt —> To Do list, for continued development of the open source Flowgen tool.
LICENSE.txt —> License agreement
README.txt —> Information
clang/ —> FOLDER with Clang-Python3 bindings, used by Flowgen
htmlCSSandJS/ --> FOLDER with CSS and Javascript files that are copied 
                  into the '/flowdoc' SUBFOLDER of any project by the Flowgen script, 
                  and which are needed by the output HTML files
example/  —> FOLDER with sample application
      /make_WIN.bat —> Flowgen executable for WINDOWS
      /Makefile —> Makefile for systems that have the Make utility. 
                   It can be used to compile the C++ code or to run Flowgen
      /simple_demo_src.cpp —> sample C++ source file with main() function  
      /include/ —> SUB-FOLDER with sample C++  headers
      /src/ —> SUB-FOLDER with sample C++  source files
      /flowdoc/ —> SUB-FOLDER with documentation generated by flowgen 
                   (this whole folder can be erased and regenerated via Flowgen)
              /*.html —> the output HTML documentation files
              /aux_files/ —> SUB-SUB-FOLDER with auxiliary files created by Flowgen: 
                             - database files (.flowdb)
                             - diagrams (.png), 
                             - CMAPX files which are used by the HTML output files 
                               to generate hyperlinks in the PNG diagram files.
                             - PlantUML diagram-descriptions (*.txt)  
                               (they can be used as input to PlantUML)