From 79bf8ebcf569951e23d7f2b4dfe138982b898101 Mon Sep 17 00:00:00 2001 From: Brent Yorgey Date: Mon, 13 May 2024 12:25:00 -0500 Subject: [PATCH] Update sublibrary graph generation script & cabal description (#1849) As a follow-up to #1834: - Update the sublibrary graph generation script so it works with the no-longer-linear graph - Regenerate the actual image - Update the `.cabal` description to match --- docs/image/sublibrary-graph.svg | 136 ++++++++++-------- scripts/gen/render-sublibrary-dependencies.sh | 19 ++- swarm.cabal | 19 ++- 3 files changed, 106 insertions(+), 68 deletions(-) diff --git a/docs/image/sublibrary-graph.svg b/docs/image/sublibrary-graph.svg index 7322cb7b..d68ef25c 100644 --- a/docs/image/sublibrary-graph.svg +++ b/docs/image/sublibrary-graph.svg @@ -4,88 +4,106 @@ - - + + plan - - + + -swarm-0.5.0.0:exe:swarm - -swarm-0.5.0.0:exe:swarm +swarm + +swarm - + -swarm-0.5.0.0:lib:swarm-web - -swarm-0.5.0.0:lib:swarm-web +swarm-web + +swarm-web - + -swarm-0.5.0.0:exe:swarm->swarm-0.5.0.0:lib:swarm-web - - +swarm->swarm-web + + - + -swarm-0.5.0.0 - -swarm-0.5.0.0 +swarm-doc + +swarm-doc - + -swarm-0.5.0.0:lib:swarm-web->swarm-0.5.0.0 - - +swarm-web->swarm-doc + + - + -swarm-0.5.0.0:lib:swarm-engine - -swarm-0.5.0.0:lib:swarm-engine +swarm-tui + +swarm-tui - + -swarm-0.5.0.0->swarm-0.5.0.0:lib:swarm-engine - - +swarm-web->swarm-tui + + - + -swarm-0.5.0.0:lib:swarm-scenario - -swarm-0.5.0.0:lib:swarm-scenario +swarm-engine + +swarm-engine - + -swarm-0.5.0.0:lib:swarm-engine->swarm-0.5.0.0:lib:swarm-scenario - - +swarm-doc->swarm-engine + + - - -swarm-0.5.0.0:lib:swarm-lang - -swarm-0.5.0.0:lib:swarm-lang - - + -swarm-0.5.0.0:lib:swarm-scenario->swarm-0.5.0.0:lib:swarm-lang - - +swarm-tui->swarm-engine + + - - -swarm-0.5.0.0:lib:swarm-util - -swarm-0.5.0.0:lib:swarm-util + + +swarm-scenario + +swarm-scenario - + -swarm-0.5.0.0:lib:swarm-lang->swarm-0.5.0.0:lib:swarm-util - - +swarm-engine->swarm-scenario + + + + + +swarm-lang + +swarm-lang + + + +swarm-scenario->swarm-lang + + + + + +swarm-util + +swarm-util + + + +swarm-lang->swarm-util + + diff --git a/scripts/gen/render-sublibrary-dependencies.sh b/scripts/gen/render-sublibrary-dependencies.sh index 689b795c..d3d613ad 100755 --- a/scripts/gen/render-sublibrary-dependencies.sh +++ b/scripts/gen/render-sublibrary-dependencies.sh @@ -7,7 +7,6 @@ cd $SCRIPT_DIR/../.. # # cabal install cabal-plan - # If the swarm.cabal file has changed, you may need to remove # the 'plan.json' file from the cache and regenerate. # @@ -16,4 +15,20 @@ cd $SCRIPT_DIR/../.. rm -r dist-newstyle/cache cabal build --dry-run -cabal-plan --hide-global --hide-builtin dot --tred --root swarm | twopi -Tsvg -o docs/image/sublibrary-graph.svg \ No newline at end of file +# Use cabal-plan to generate a graph of sublibrary dependencies. +# The --tred flag indicates to use transitive reduction, i.e. +# remove edges A -> C when there are edges A -> B -> C +cabal-plan --hide-global --hide-builtin dot --tred --root swarm | + + # The vertices generated by cabal-plan have names like + # 'swarm-0.5.0.0:lib:swarm-tui'; this sed command strips off + # the first two parts from each name leaving only e.g. 'swarm-tui' + sed 's/"swarm-[^:]*:\(lib\|exe\):/"/g' | + + # The graph output by cabal-plan has "rankdir=LR" which lays + # out the layers from left to right; we prefer them to be laid out + # bottom to top. + sed 's/LR/BT/' | + + # Finally, use dot to render the generated graph to an SVG. + dot -Tsvg -o docs/image/sublibrary-graph.svg diff --git a/swarm.cabal b/swarm.cabal index 672b959b..ef43b831 100644 --- a/swarm.cabal +++ b/swarm.cabal @@ -14,17 +14,22 @@ description: == Module organization For developers getting oriented, Swarm's modules are organized into - sublibraries, from inner to outer: + sublibraries. Roughly in order from inner to outer, they are: - * utilities - * swarm language - * swarm scenario - * swarm game engine - * swarm TUI - * swarm app + * swarm-util: miscellaneous utilities + * swarm-lang: parsing, typechecking, etc. for the Swarm language + * swarm-scenario: scenario descriptions, parsing, & processing + * swarm-engine: game simulation + * swarm-doc: generating documentation + * swarm-tui: textual user interface + * swarm-web: web interface + * swarm: the swarm executable <> + See the [Swarm module guide](https://github.com/swarm-game/swarm/wiki/Module-guide) + for a more in-depth guide to the codebase. + license: BSD-3-Clause license-file: LICENSE author: Brent Yorgey