Skip to content

Commit

Permalink
Update README.md
Browse files Browse the repository at this point in the history
  • Loading branch information
@mpeterv
mpeterv committed Dec 18, 2015
1 parent 27386d8 commit 6c52ead
Showing 1 changed file with 42 additions and 166 deletions.
208 changes: 42 additions & 166 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,200 +2,76 @@

[![Build Status](https://travis-ci.org/mpeterv/depgraph.svg?branch=master)](https://travis-ci.org/mpeterv/depgraph) [![Coverage Status](https://coveralls.io/repos/mpeterv/depgraph/badge.svg?branch=master&service=github)](https://coveralls.io/github/mpeterv/depgraph?branch=master)

depgraph provides `luadepgraph` command-line tool for building, analyzing, and visualizing graph of dependencies between Lua modules within a package.
depgraph provides `luadepgraph` command-line tool for building, analyzing, and visualizing graph of dependencies between Lua modules within a package. To install it using [LuaRocks](https://luarocks.org), open terminal and run `luarocks install depgraph` or `sudo luarocks install depgraph`.

## Status
`luadepgraph` scans all passed files, looking for [`require`](http://www.lua.org/manual/5.3/manual.html#pdf-require) calls. It distinguishes several types of dependencies based on call context:

It works. The first official release is coming sooner rather than later.
* A dependency is *lazy* if `require` is called inside a function;
* A dependency is *conditional* if `require` is called within a branch of an `if` statement;
* A dependency is *protected* if `require` is called using [`pcall`](http://www.lua.org/manual/5.3/manual.html#pdf-pcall) or [`xpcall`](http://www.lua.org/manual/5.3/manual.html#pdf-xpcall).

## Installation
Dependency target is inferred from the argument passed to `require` if it's a literal string or a concatenation of a string and another expression.

Using LuaRocks: clone this repo, `cd` into it, run `luarocks make`.
## Specifying Lua files

## Usage
`luadepgraph` needs to know which Lua files are part of the package and have to be included in its dependency graph. It can handle two types of files: regular modules and external files that can't be imported from other files, but can depend on modules, e.g. scripts and test files.

An invocation of `luadepgraph` consists of two parts.
Modules are specified using `-m/--modules` option and external files are added using `-e/--ext-files`. Both options accept several files or directories. `-m/--modules` also accepts rockspecs; if no modules are added but there is a single rockspec in current directory, it is be used automatically.

The first is to tell it how to find Lua modules to be added to the graph using `-m` option. It can be used several times, and accepts files, directories, and rockspecs. If not using a rockspec, pass prefix directory from where modules can be loaded using `-p`, e.g. if modules `foo.*` are in `src/foo/*.lua`, pass `-m src/foo -p src`. On the other hand, if there is a single rockspec in current directory, skip this step completely, it will be used automatically.
Unless using a rockspec, pass prefix directory from where Lua modules can be loaded using `-p/--prefix`.

You can also add external files that are not Lua modules themselves but can depend on modules, e.g. examples, tests, scripts, using `-e` option. It can accept directories, too.
## Graph actions

The second part is to tell `luadepgraph` what it should do with the graph. Currently you can print list of all nodes using `list` command,
show all information about a particular module using `show`, show external dependencies using `deps`, look for circular dependencies using `cycles`, and export the graph into .dot format using `dot`.
`luadepgraph` can perform several actions on the graph:

* `--list`: print a listing of modules and external files in the graph. This is the default action.
* `--show <module>`: print all information about a module, which includes its location, dependencies and dependents. External files can be passed by file name.
* `--deps`: print a listing of all external dependencies of the graph.
* `--cycles`: look for circular dependencies and show the shortest ones.
* `--dot [<title>]`: export the graph in .dot format, which can be turned into an image using [Graphviz](http://www.graphviz.org/).

There are some options that can preprocess or filter the graph before executing an action, run `luadepgraph -h` for more info.

## Examples

From Penlight root directory:
List all modules in `src` directory:

```
luadepgraph list
39 modules, 0 external files.
Modules:
pl in lua/pl/init.lua
pl.Date in lua/pl/Date.lua
pl.List in lua/pl/List.lua
pl.Map in lua/pl/Map.lua
pl.MultiMap in lua/pl/MultiMap.lua
pl.OrderedMap in lua/pl/OrderedMap.lua
pl.Set in lua/pl/Set.lua
pl.app in lua/pl/app.lua
pl.array2d in lua/pl/array2d.lua
pl.class in lua/pl/class.lua
pl.compat in lua/pl/compat.lua
pl.comprehension in lua/pl/comprehension.lua
pl.config in lua/pl/config.lua
pl.data in lua/pl/data.lua
pl.dir in lua/pl/dir.lua
pl.file in lua/pl/file.lua
pl.func in lua/pl/func.lua
pl.import_into in lua/pl/import_into.lua
pl.input in lua/pl/input.lua
pl.lapp in lua/pl/lapp.lua
pl.lexer in lua/pl/lexer.lua
pl.luabalanced in lua/pl/luabalanced.lua
pl.operator in lua/pl/operator.lua
pl.path in lua/pl/path.lua
pl.permute in lua/pl/permute.lua
pl.pretty in lua/pl/pretty.lua
pl.seq in lua/pl/seq.lua
pl.sip in lua/pl/sip.lua
pl.strict in lua/pl/strict.lua
pl.stringio in lua/pl/stringio.lua
pl.stringx in lua/pl/stringx.lua
pl.tablex in lua/pl/tablex.lua
pl.template in lua/pl/template.lua
pl.test in lua/pl/test.lua
pl.text in lua/pl/text.lua
pl.types in lua/pl/types.lua
pl.url in lua/pl/url.lua
pl.utils in lua/pl/utils.lua
pl.xml in lua/pl/xml.lua
luadepgraph -m src -p src
```

Show dependencies and dependents of module `rock.foo`:

```
luadepgraph show pl.utils
Module pl.utils in lua/pl/utils.lua
Dependencies:
* on line 82, column 13 (lazy)
pl.compat on line 5, column 16
pl.operator on line 329, column 31 (lazy)
Depended on by:
pl.Date on line 11, column 15
pl.List on line 26, column 15
pl.Map on line 13, column 15
pl.MultiMap on line 8, column 15
pl.OrderedMap on line 9, column 15
pl.Set on line 26, column 15
pl.app on line 8, column 15
pl.array2d on line 12, column 15
pl.comprehension on line 33, column 15
pl.data on line 20, column 15
pl.dir on line 7, column 15
pl.file on line 6, column 15
pl.func on line 23, column 15
pl.import_into as pl.* (2 times)
on line 37, column 17 (lazy)
on line 65, column 26 (lazy)
pl.import_into on line 33, column 21 (lazy)
pl.input on line 16, column 15
pl.operator on line 15, column 15
pl.path on line 18, column 15
pl.permute on line 6, column 15
pl.pretty on line 10, column 15
pl.seq on line 12, column 15
pl.stringx on line 11, column 15
pl.tablex on line 7, column 15
pl.template on line 31, column 15
pl.test on line 12, column 15
pl.text on line 23, column 15
pl.types on line 6, column 15
pl.xml on line 32, column 15
luadepgraph -m src -p src --show rock.foo
```

List all modules used by unit test `spec/foo_spec.lua`:

```
luadepgraph dot | dot -Tgif -o pl.gif
luadepgraph -m src -p src -e spec --root spec/foo_spec.lua
```

[![Penlight dependency graph](http://i.imgur.com/UyZG3y4.gif)](http://i.imgur.com/UyZG3y4.gif)
Show external dependencies of a package given a rockspec:

```
luadepgraph -m rockspecs/rock-1.0-1.rockspec --deps
```

From LuaRocks root directory:
Look for circular dependencies:

```
luadepgraph -m src/luarocks -p src -e src/bin cycles
11 circular dependencies found.
The shortest circular dependency has length 1:
luarocks.fetch depends on luarocks.fetch on line 374, column 15 (lazy)
The next shortest circular dependency has length 2:
luarocks.build depends on luarocks.install on line 380, column 23 (lazy)
luarocks.install depends on luarocks.build on line 172, column 21 (lazy)
The next shortest circular dependency has length 2:
luarocks.cfg depends on luarocks.util on line 20, column 14
luarocks.util depends on luarocks.cfg (2 times)
on line 268, column 16 (lazy)
on line 486, column 16 (lazy)
The next shortest circular dependency has length 2:
luarocks.deps depends on luarocks.fetch on line 697, column 18 (lazy)
luarocks.fetch depends on luarocks.deps on line 11, column 14
The next shortest circular dependency has length 2:
luarocks.deps depends on luarocks.install on line 419, column 20 (lazy)
luarocks.install depends on luarocks.deps on line 12, column 14
The next shortest circular dependency has length 2:
luarocks.deps depends on luarocks.search on line 418, column 19 (lazy)
luarocks.search depends on luarocks.deps on line 11, column 14
The next shortest circular dependency has length 2:
luarocks.fs depends on luarocks.fs.lua on line 66, column 16
luarocks.fs.lua depends on luarocks.fs on line 7, column 12
The next shortest circular dependency has length 2:
luarocks.manif depends on luarocks.repos on line 18, column 15
luarocks.repos depends on luarocks.manif on line 12, column 15
The next shortest circular dependency has length 2:
luarocks.manif depends on luarocks.search on line 14, column 16
luarocks.search depends on luarocks.manif on line 10, column 15
The next shortest circular dependency has length 3:
luarocks.deps depends on luarocks.manif_core on line 19, column 20
luarocks.manif_core depends on luarocks.type_check on line 9, column 20
luarocks.type_check depends on luarocks.deps on line 9, column 14
The next shortest circular dependency has length 4:
luarocks.cfg depends on luarocks.persist on line 42, column 17
luarocks.persist depends on luarocks.util on line 10, column 14
luarocks.util depends on luarocks.fs on line 49, column 15 (lazy)
luarocks.fs depends on luarocks.cfg on line 14, column 13
luadepgraph -m rockspecs/rock-1.0-1.rockspec --cycles
```

Same, but ignore lazy dependencies:

```
luadepgraph -m src/luarocks -p src -e src/bin deps
12 external dependencies.
debug required by:
luarocks.util on line 13, column 15
lfs required by:
luarocks.fs.lua on line 22, column 24 (conditional, protected)
ltn12 required by:
luarocks.fs.lua on line 558, column 15 (conditional)
luarocks.upload.api on line 123, column 31 (protected)
luarocks.site_config required by:
luarocks.cfg on line 28, column 28 (conditional, protected)
md5 required by:
luarocks.fs.lua on line 23, column 24 (conditional, protected)
mimetypes required by:
luarocks.upload.multipart on line 19, column 45 (lazy, protected)
posix required by:
luarocks.fs.lua on line 24, column 28 (conditional, protected)
socket.ftp required by:
luarocks.fs.lua on line 19, column 19 (conditional, protected)
socket.http required by:
luarocks.fs.lua on line 18, column 28 (conditional, protected)
luarocks.upload.api (2 times)
on line 208, column 32 (lazy, protected)
on line 214, column 29 (lazy, protected)
ssl.https required by:
luarocks.fs.lua on line 559, column 32 (conditional, protected)
luarocks.upload.api on line 200, column 29 (lazy, protected)
zip required by:
luarocks.fs.lua on line 21, column 29 (conditional, protected)
zlib required by:
luarocks.tools.zip on line 7, column 14
luadepgraph -m rockspecs/rock-1.0-1.rockspec --cycles --strict
```

## License
Turn the graph into an image (`dot` command-line tool is a part of Graphviz):

MIT.
```
luadepgraph -m rockspecs/rock-1.0-1.rockspec --dot | dot -Tgif -o rock.gif
```

0 comments on commit 6c52ead

Please sign in to comment.