fc4-framework

fc4-tool

A tool for reorganizing, restructuring, reformatting, and rendering FC4 diagrams.

CircleCI codecov

Purpose

As explained in The Toolset section of the FC4 Methodology:

This tool was created because when one uses Structurizr Express (SE) to position the elements of a diagram, SE regenerates the diagram source YAML in such a way that the YAML becomes noisy and the sorting can change. This makes the source harder to work with in a text editor and impossible to usefully diff from revision to revision — and without useful diffing it’s very difficult to do effective peer review.

So fc4-tool processes the YAML: cleans it up, applies a stable sort to all properties, removes empty properties, etc — so as to ensure that the changes applied in each revision are very small and specific and all extraneous changes are filtered out. This will hopefully enable effective peer review of revisions to the diagrams.

fc4-tool also:

Setup

Requirements

  1. A Java Runtime Environment (JRE) or Java Development Kit (JDK)
    1. On MacOS if you have Homebrew you can run brew cask install adoptopenjdk
  2. An installation of Chrome or Chromium 70–72 (inclusive)
    1. On MacOS:
      1. If you have Homebrew you can run brew cask install chromium
      2. Chromium/Chrome must be at either /Applications/Chromium.app or /Applications/Google Chrome.app

MacOS quick-start for Homebrew users: brew cask install adoptopenjdk chromium

Download and Install

  1. Download the archive from your platform from the latest release on the releases page
  2. Expand the archive then move the extracted files to somewhere on your $PATH
    1. e.g. mv ~/Downloads/fc4/fc4* ~/bin/

Editing and Rendering Diagrams

Basic Workflow

  1. Run in your terminal: fc4 wcb
  2. Copy-and-paste YAML diagram definitions between Structurizr Express (SE) and an open file in your text editor.
  3. When done, ensure the YAML in your editor is the latest version, copy-and-pasting from SE one last time if necessary, then save the file.
  4. Switch to your terminal and hit ctrl-c to stop fc4-tool
  5. Run fc4 render path/to/diagram.yaml to generate a .png file alongside the .yaml file
  6. Commit both files

Full Workflow

Please see The Authoring Workflow section of the FC4 Methodology.

Requirements and Prerequisites for Development and Testing

Required

Running the Tests

  1. Use CI
  2. No, seriously, use CI!
  3. Just kidding, I know sometimes you need to run the tests locally ;)

With Docker

Run this in your shell:

bin/run bin/tests

Without Docker

If you’re old-school and prefer to run tests on bare metal:

  1. Ensure that Clojure, Node, and Chromium/Chrome are installed
    1. On Macos with Homebrew: brew cask install adoptopenjdk chromium && brew install clojure npm
  2. Run:
    1. bin/download-all-deps
    2. bin/tests

Starting a REPL for Dev/Test

You could just run clj but you’re likely to want the test deps and dev utils to be accessible. So you’ll probably want to run clj -A:dev:test

Running the tests in a REPL

$ clj -A:dev:test
Clojure 1.9.0
user=> (require '[eftest.runner :refer [find-tests run-tests]])
user=> (run-tests (find-tests "test") {:fail-fast? true})
...

Running the Linter

For linting, this project uses cljfmt, via cljfmt-runner.

Building an Uberjar

You’ll need to be using Java 9 or 10; 11 or higher cannot currently compile the project (see issue #85).

# From <repo-root>/tool/ run:
bin/uberjar

Since you need to use Java 8/9/10 to compile the project but then Java 11 to validate the uberjar, you might find jenv useful. (I discovered it via Multiple JVM versions on macOS by Pete Woods.)

Contributors

Thank you all!

(If you notice that anyone is missing from this list, please open an issue or a PR — thank you!)