Merge pull request #1104 from TristanCacqueray/just

Introduce Justfile

CONTRIBUTING.md

@@ -33,31 +33,34 @@ This section describes how to start the Monocle services directly on your host.
 #### Start ElasticSearch
 
 ```ShellSession
-nix develop --command elasticsearch-start
+just elastic
 ```
 
 #### Start the Monocle API
 
 The API serves the web UI and the Monocle API. The web App must be built first by running:
 
 ```ShellSession
-cd web && npm install && npm run build && cd -
+just build-web
 ```
 
 Then, ensure you have set the Monocle config file `config.yaml` (see [README.md](README.md#configuration)) and run:
 
 ```ShellSession
-nix develop --command monocle-repl
+just repl
 λ> import Monocle.Main
 λ> run $ defaultApiConfig 8080 "http://localhost:19200" "etc/config.yaml"
 ```
 
 … or by running the executable:
 
 ```ShellSession
-CRAWLERS_API_KEY=secret MONOCLE_CONFIG=./etc/config.yaml nix develop --command cabal run -O0 monocle -- api
+just api
 ```
 
+> Make sure to setup your .env file, e.g. with:
+> (echo CRAWLERS_API_KEY=secret; echo MONOCLE_CONFIG=./etc/config.yaml) > .env
+
 The Monocle UI should be accessible:
 
 ```ShellSession
@@ -67,11 +70,14 @@ firefox http://localhost:8080
 #### Start the Monocle crawler process
 
 ```ShellSession
-nix develop --command monocle-repl
-λ> import Macroscope.Worker
-λ> import Macroscope.Main
-λ> import Monocle.Client (withClient)
-λ> withClient "http://localhost:8080" Nothing $ \client -> runMacroscope 19001 "etc/config.yaml" client
+just repl
+λ> Monocle.Client.withClient "http://localhost:8080" Nothing $ \client -> Macroscope.Main.runMacroscope 19001 "etc/config.yaml" client
+```
+
+… or by running the executable:
+
+```ShellSession
+just crawler
 ```
 
 ### Start the CLI
@@ -88,6 +94,14 @@ For instance running a crawler:
 nix run . -- lentille github-projects --url https://api.github.com/graphql --token <a-valid-token> --organization change-metrics
 ```
 
+### Build the documentation
+
+Build and read the code documentation:
+
+```
+just docs
+```
+
 ## nix-develop
 
 The nix develop shell provides development tooling such as:
@@ -113,19 +127,20 @@ You might need to install the right Haskell plugin for your editor.
 ghcid automatically re-compiles the code when a haskell file change and display compilation
 errors and warnings.
 
-
 ```ShellSession
-nix develop --command monocle-ghcid
+just ghcid
 ```
 
 ### Run hoogle
 
 Hoogle generates the documentation from the Monocle source code.
 
 ```ShellSession
-nix develop --command hoogle server -p 8081 --local --haskell
+just hoogle-monocle
 ```
 
+> To avoid building monocle, you can start hoogle with only the dependencies using `just hoogle`
+
 You can access the generated documentation on port 8081.
 
 ## Running tests
@@ -136,33 +151,33 @@ Ensure the service is started by running: `nix develop --command elasticsearch-s
 Run linters (fourmolu and hlint) with:
 
 ```ShellSession
-nix develop --command monocle-fast-ci-run
+just ci-fast
 ```
 
 When the linters fail, you can fix the issue automatically with:
 
 ```ShellSession
-nix develop --command monocle-reformat-run
+just fmt
 ```
 
 Run the full test suite with:
 
 ```ShellSession
-nix develop --command monocle-ci-run
+just ci
 ```
 
-Run a single test:
+Run a single test (on failure, tasty provides a pattern to re-run a single test):
 
 ```ShellSession
-cabal test --test-options='-p "Change stream"'
+just test "PATTERN"
 ```
 
 ## Start the web development server
 
 Start the web dev server (hot-reload):
 
 ```ShellSession
-nix develop --command monocle-web-start
+just web
 firefox http://localhost:13000
 ```
 
@@ -188,7 +203,7 @@ ghcid --set ":set args api" --test 'CLI.main'
 Start Kibana with:
 
 ```ShellSession
-nix develop --command kibana-start
+just kibana
 ```
 
 Then access http://localhost:5601
@@ -198,9 +213,8 @@ Then access http://localhost:5601
 Provisonning fake data (only fake changes are supported) can be done using the repl:
 
 ```
-nix develop --command monocle-repl
-λ> import Monocle.Backend.Provisioner
-λ> runProvisioner "etc/config.yaml" "http://localhost:19200" "demo-fake-data" 300
+just repl
+λ> Monocle.Backend.Provisioner.runProvisioner "etc/config.yaml" "http://localhost:19200" "demo-fake-data" 300
 ```
 
 Prior to run the provisonner, add the *demo-fake-data* workspace in the config file with an
@@ -214,7 +228,7 @@ protobuf definitions present in the [./schemas/monocle folder](./schemas/monocle
 the api and web client by running the protoc command using the Makefile:
 
 ```ShellSession
-$ make codegen
+just codegen
 ```
 
 ## Create a monocle build

Justfile

@@ -0,0 +1,130 @@
+# Copyright (C) 2023 Monocle authors
+# SPDX-License-Identifier: AGPL-3.0-or-later
+#
+# doc: https://just.systems/man/en/chapter_1.html
+
+# Load .env file
+set dotenv-load
+
+PINCLUDE := "-I /usr/include ${PROTOC_FLAGS} -I ./schemas/"
+# just doesn't support array so we create a space separated string for bash
+# see: https://github.com/casey/just/issues/1570
+PBS := `ls schemas/monocle/protob/*.proto | grep -v http.proto | sed 's/schemas.//' | tr '\n' ' '`
+
+# Start elasticsearch
+elastic:
+    nix develop --command elasticsearch-start
+
+# Start kibana
+kibana:
+    nix develop --command kibana-start
+
+# Start web devel server
+web:
+    nix develop --command monocle-web-start
+
+# Build the web interface
+build-web:
+    cd web && npm install && npm run build
+
+# Reformat and apply hlint hints
+fmt:
+    nix develop --command monocle-reformat-run
+
+# Run the full ci test suite
+ci:
+    nix develop --command monocle-ci-run
+
+# Run unit tests
+ci-fast:
+    nix develop --command monocle-fast-ci-run
+
+test pattern:
+    nix develop --command cabal -O0 test --test-options='-p "{{pattern}}"'
+
+# Start ghcid
+ghcid:
+    nix develop --command ghcid
+
+# Build and open the documentation
+docs:
+    nix develop --command cabal haddock --open
+
+# Start hoogle with local monocle documentation
+hoogle-monocle:
+    nix develop .#hoogle-monocle --command hoogle server -p 8081 --local --haskell
+
+# Start hoogle to search documentation
+hoogle:
+    nix develop .#hoogle --command hoogle server -p 8081 --local --haskell
+
+# Start a ghci repl
+repl:
+    nix develop --command monocle-repl
+
+# Run the API
+api:
+    nix develop --command cabal run -O0 monocle -- api
+
+# Run the CRAWLER
+crawler:
+    nix develop --command cabal run -O0 monocle -- crawler
+
+# Update code after changing protobuf schema (./schemas/monocle/protob), ci.dhall or architecture.plantuml
+codegen: codegen-ci codegen-doc codegen-stubs codegen-javascript codegen-openapi codegen-haskell
+
+# Generate CI config from .github/workflows/ci.dhall
+[private]
+codegen-ci:
+    set -euxo pipefail
+    echo "(./.github/workflows/ci.dhall).Nix" | dhall-to-yaml > .github/workflows/nix.yaml
+    echo "(./.github/workflows/ci.dhall).NixBuild" | dhall-to-yaml > .github/workflows/nix-build.yaml
+    echo "(./.github/workflows/ci.dhall).Web" | dhall-to-yaml > .github/workflows/web.yaml
+    echo "(./.github/workflows/ci.dhall).Docker" | dhall-to-yaml > .github/workflows/docker.yaml
+    echo "(./.github/workflows/ci.dhall).Publish-Master-Image" | dhall-to-yaml > .github/workflows/publish-master.yaml
+    echo "(./.github/workflows/ci.dhall).Publish-Tag-Image" | dhall-to-yaml > .github/workflows/publish-tag.yaml
+
+# Generate doc/architecture.png from doc/architecture.plantuml
+# just doesn't support timestamp based rule, so we keep make for plantuml
+# see: https://github.com/casey/just/issues/867
+[private]
+codegen-doc:
+    set -euxo pipefail
+    make doc/architecture.png
+
+# Generate HTTP clients and server
+[private]
+codegen-stubs:
+    set -euxo pipefail
+    mkdir -p srcgen/
+    cabal -fcodegen run monocle-codegen ./schemas/monocle/protob/http.proto ./src/Monocle/Client/Api.hs ./src/Monocle/Servant/HTTP.hs ./srcgen/WebApi.res
+    fourmolu -i ./src/Monocle/Client/Api.hs ./src/Monocle/Servant/HTTP.hs
+    ./web/node_modules/.bin/bsc -format ./srcgen/WebApi.res > ./web/src/components/WebApi.res
+    rm -Rf srcgen/
+
+# Generate haskell data type from protobuf
+[private]
+codegen-haskell:
+    set -euxo pipefail
+    for pb in {{PBS}}; do \
+      compile-proto-file --includeDir /usr/include --includeDir schemas/ --includeDir ${PROTOBUF_SRC} --proto ${pb} --out codegen/; \
+    done
+    find codegen/Monocle -type f -name "*.hs" -exec sed -i {} -e '1i{-# LANGUAGE NoGeneralisedNewtypeDeriving #-}' \;
+    fourmolu -i codegen/Monocle
+
+# Generate javascript data type from protobuf
+[private]
+codegen-javascript:
+    set -euxo pipefail
+    rm -f web/src/messages/*
+    for pb in {{PBS}}; do \
+      ocaml-protoc {{PINCLUDE}} -bs -ml_out web/src/messages/ schemas/${pb}; \
+    done
+    python3 ./codegen/rename_bs_module.py ./web/src/messages/
+
+# Generate openapi from protobuf
+[private]
+codegen-openapi:
+    set -euxo pipefail
+    protoc {{PINCLUDE}} --openapi_out=./doc/ monocle/protob/http.proto
+    echo Created doc/openapi.yaml

Makefile

@@ -1,43 +1,5 @@
 # Copyright (C) 2021 Monocle authors
 # SPDX-License-Identifier: AGPL-3.0-or-later
-.PHONY: up-stage
-
-
-BASEDIR = monocle/protob
-MESSAGES = $(BASEDIR)/search.proto $(BASEDIR)/config.proto $(BASEDIR)/login.proto $(BASEDIR)/metric.proto $(BASEDIR)/auth.proto
-CRAWLER = $(BASEDIR)/change.proto $(BASEDIR)/issue.proto $(BASEDIR)/crawler.proto
-PINCLUDE = -I /usr/include $(PROTOC_FLAGS) -I ./schemas/
-
-codegen: codegen-ci codegen-javascript codegen-stubs codegen-openapi codegen-haskell doc/architecture.png
-
-codegen-ci:
-	echo "(./.github/workflows/ci.dhall).Nix" | dhall-to-yaml > .github/workflows/nix.yaml
-	echo "(./.github/workflows/ci.dhall).NixBuild" | dhall-to-yaml > .github/workflows/nix-build.yaml
-	echo "(./.github/workflows/ci.dhall).Web" | dhall-to-yaml > .github/workflows/web.yaml
-	echo "(./.github/workflows/ci.dhall).Docker" | dhall-to-yaml > .github/workflows/docker.yaml
-	echo "(./.github/workflows/ci.dhall).Publish-Master-Image" | dhall-to-yaml > .github/workflows/publish-master.yaml
-	echo "(./.github/workflows/ci.dhall).Publish-Tag-Image" | dhall-to-yaml > .github/workflows/publish-tag.yaml
 
 doc/architecture.png: doc/architecture.plantuml
 	plantuml ./doc/architecture.plantuml
-
-codegen-stubs:
-	mkdir -p srcgen/
-	(cabal -fcodegen run monocle-codegen ./schemas/$(BASEDIR)/http.proto ./src/Monocle/Client/Api.hs ./src/Monocle/Servant/HTTP.hs ./srcgen/WebApi.res)
-	fourmolu -i ./src/Monocle/Client/Api.hs ./src/Monocle/Servant/HTTP.hs
-	./web/node_modules/.bin/bsc -format ./srcgen/WebApi.res > ./web/src/components/WebApi.res
-	rm -Rf srcgen/
-
-codegen-haskell:
-	sh -c 'for pb in $(MESSAGES) $(CRAWLER); do compile-proto-file --includeDir /usr/include --includeDir schemas/ --includeDir ${PROTOBUF_SRC} --proto $${pb} --out codegen/; done'
-	find codegen/Monocle -type f -name "*.hs" -exec sed -i {} -e '1i{-# LANGUAGE NoGeneralisedNewtypeDeriving #-}' \;
-	fourmolu -i codegen/Monocle
-
-codegen-javascript:
-	rm -f web/src/messages/*
-	sh -c 'for pb in $(MESSAGES) $(CRAWLER); do ocaml-protoc $(PINCLUDE) -bs -ml_out web/src/messages/ schemas/$${pb}; done'
-	python3 ./codegen/rename_bs_module.py ./web/src/messages/
-
-codegen-openapi:
-	protoc $(PINCLUDE) --openapi_out=./doc/ $(BASEDIR)/http.proto
-	@echo Created doc/openapi.yaml

doc/tutorial/protobuf.md

@@ -161,5 +161,5 @@ We would like to avoid doing the above manually, thus Monocle provide a codegen
 to automate this process in three steps:
 
 - 1. Write protobuf definitions in the `schemas/` folder, (and add newly created files to the Makefile `MESSAGES` list)
-- 2. Generate the code by running `make codegen-with-container`
+- 2. Generate the code by running `just codegen`
 - 3. Implement the API, e.g. open the `web/src/components/WebApi.res` module to use it.

flake.nix

@@ -38,6 +38,8 @@
     in {
       haskellExtend = legacy.hExtend;
       devShell."x86_64-linux" = legacy.shell;
+      devShells."x86_64-linux".hoogle-monocle = legacy.hoogle-monocle;
+      devShells."x86_64-linux".hoogle = legacy.hoogle;
       devShells."x86_64-linux".ci = legacy.ci-shell;
       devShells."x86_64-linux".monitoring = legacy.monitoring-shell;
       packages."x86_64-linux".default = legacy.monocle-exe;