depends-public/README.md

141 lines
8.4 KiB
Markdown

# Introduction
*Depends* is a source code dependency extraction tool, designed to infer syntactical relations among source code entities, such as files and methods, from various programming languages. Our objective is to provide a framework that is easily extensible to support dependency extraction from different programming languages and configuration files, so that other high-level analysis tools can be built upon it, in a language-independent fashion. Sample applications include code visualization, program comprehension, code smell detection, architecture analysis, design refactoring, etc.
Our creation of *Depends* is motivated by the observations that different vendors, such as Understand™, Structure 101 ™, and Lattix™, created their own dependency extraction tools that are packaged with their other analysis functions. To conduct new analysis, vendors and researchers must each create their own dependency extraction tools, or use the output of other tools, which are usually not designed to be reusable.
We believe that dependency analysis of software source code is one of the most important foundations of software engineering. Given the growing number of systems built on new languages and multi-languages, the need of a flexible, extensible multi-language dependency extraction framework, with simple and unified interfaces is widely recognized.
*Depends* is open source and free, to promote community collaboration, to avoid repetitive work, and to improve the quality of analytical tools.
# How to use *Depends*
## Download and installation
You could download the latest version of *Depends* from https://github.com/multilang-depends/depends/releases/,
and then unzip the ```depends-*version*.tgz``` file in any directory of your computer.
*Depends* is written in java, so it could be run on any OS with a JRE or JDK environment (like Windows, Linux or Mac OS).
## Run it from command line
Following the single responsibility principle, *Depends* is designed for the purpose of extracting dependencies only. It only provides CLI interface, without GUI. But you can convert the output of *Depends* into the GUI of other tools, such as GraphViz(http://graphviz.org/), PlantUML(http://plantuml.com/), and DV8 (https://www.archdia.com).
You could run *Depends* in the following ways: ```depends.sh``` on Linux/Mac, ```depends.bat``` on Microsoft Windows, or ```java -jar depends.jar```.
Note: If you encountered Out of Memory error like ```GC overhead limt exceed```, please expand
the JVM memory like following ```java -Xmx4g -jar depends.jar <args>```.
## Parameters
The CLI tool usage could be listed by ```depends --help```, like following:
Usage: depends [-hms] [--auto-include] [-d=<dir>] [-g=<granularity>]
[-p=<namePathPattern>] [-f=<format>[,<format>...]]...
[-i=<includes>[,<includes>...]]... <lang> <src> <output>
<lang> The language of project files: [cpp, java, ruby, python,
pom]
<src> The directory to be analyzed
<output> The output file name
--auto-include auto include all paths under the source path (please
notice the potential side effect)
-i, --includes=<includes>[,<includes>...]
The files of searching path
-d, --dir=<dir> The output directory
-f, --format=<format>[,<format>...]
The output format: [json(default),xml,excel,dot,
plantuml]
-g, --granularity=<granularity>
Granularity of dependency.[file(default),method,L#(the level of folder. e.g. L1=1st level folder) ]
-h, --help Display this help and exit
-s, --strip-leading-path Strip the leading path.
-m, --map Output DV8 dependency map file.
-p, --namepattern=<namePathPattern>
The name path separators.[default(/),dot(.)
To run *Depends*, you need to specify 3 most important parameters: ```lang```, ```src```,```output```, as explained above.
## Remember to specify include paths
Please note that for most programming languages, such as ```C/C++, Ruby, Maven/Gradle```, the ```--includes``` path is important for *Depends* to find the right files when conducting code dependency analysis, similar to Makefile/IDE. Otherwise, the extracted dependencies may not be accurate.
Do not specify include paths outside of src directory (e.g. system level include paths, or external dependencies) because *Depends* will not process them.
```--auto-include``` is a useful parameter to simplify the input of include dirs: with this parameter, *Depends* will include all sub-directories of ```src```.
For ```Java``` programs, you are not required to specify include paths, because the mapping between java file paths are explicitly stated in the import statements.
### Output
The output of *Depends* can be exported into 5 formats: json, xml, excel, dot, and plantuml. Due to the limitation of MS excel, you can only export into an excel file if the number of elements is less than 256.)
Dot files could be used to generate graphs using GraphViz (http://graphviz.org/).
Plantuml files could be used to generate UML diagram using PlantUML (http://plantuml.com/).
Json and XML files could be used to generate Design Structure Matrices (DSMs) using DV8 (https://www.archdia.net).
The detail of json/xml format could be found [here](./doc/output_format.md).
### How many dependency types does *Depends* support?
*Depends* supports major dependency types, including:
* Call: function/method invoke
* Cast: type cast
* Contain: variable/field definition
* Create: create an instance of a certain type
* Extend: parent-child relation
* Implement: implemented interface
* Import/Include: for example, java ```import```, c/c++ ```#include```, ruby ```require```.
* Mixin: mix-in relation, for example ruby include
* Parameter: as a parameter of a method
* Return: returned type
* Throw: throw exceptions
* Use: use or set variables
* ImplLink: the implementation link between call and the implementation of prototype.
For detail of supported types, please refer to [here](./doc/dependency_types.md)
# How to contribute
There are many ways to contribute to *Depends*. For example:
## Support new languages
*Depends* implemented a graceful kernel for dependency analysis, which can be extended to accommodate various programming languages. So far, it only supports Java, C/C++, Ruby, and Maven. Please feel free to leverage this framework to add your own dependency extractor.
The effort needed for each language varies a lot. We spent 24 hours to support Maven, but spent weeks to extract dependencies from Ruby
## Enhance language features and fix issues
Parsing source files is not trivial. There are many language-specific features that need to be taken into consideration. Reporting unsupported language features or fixing existing issues will make *Depends* better.
## Create useful tools
You could use *Depends* as building blocks to create various tools, either open source or commercial, for productions or research, such as GUI tools, code visualization tools, etc.
## Become a sponsor
It will help us a great deal if your company or institute becomes a sponsor of our project. Your donation could help *Depends* to be independent, sustainable, and support more contributors.
# Tell us your thoughts
You are welcome to use "Depends" in your projects, either open source or commercial ones, as well as software engineering research. Your feedback is highly appreciated. We will also be thankful if you could help us spread the words and encourage more people to use it.
# Acknowledgement
This project is built upon the excellent work of other researchers, including the ENRE framework (https://github.com/jinwuxia/ENRE) proposed by Jin Wuxia et al., and the architecture research from Prof. Yuanfang Cai 's team (https://www.cs.drexel.edu/~yfcai/) on dependency analysis.
The language specific front-end of *Depends* is built upon several excellent open source projects, including Antlr/Antlr Grammar V4 (https://github.com/antlr), Eclipse CDT (www.eclipse.org/cdt), and JRuby(https://github.com/jruby/jruby).
# Authors
- Gang ZHANG (https://github.com/gangz)
- Jin Wuxia (https://github.com/jinwuxia)
# Sponsors
- ArchDia LLC. (www.archdia.com)
- Emergent Design Inc.(www.emergentdesign.cn)