From 19fda4fbd4c0b51643158827e188c9b4cb1b2296 Mon Sep 17 00:00:00 2001 From: vocksel Date: Mon, 15 Apr 2024 19:26:19 -0700 Subject: [PATCH] Use Just as our command runner instead of shell scripts (#245) Our shell scripts are getting a bit unwieldy to manage, and I've been using Just for some other projects and like it quite a bit to keep commands ("recipes") organized and discoverable --- .github/pull_request_template.md | 2 +- .github/workflows/ci.yml | 40 +++++------------- .vscode/extensions.json | 9 ++++ bin/analyze.sh | 12 ------ bin/lint.sh | 11 ----- bin/test.sh | 3 -- bin/wally-install.sh | 9 ---- docs/contributing.md | 50 ++++------------------ justfile | 71 ++++++++++++++++++++++++++++++++ 9 files changed, 101 insertions(+), 106 deletions(-) create mode 100644 .vscode/extensions.json delete mode 100755 bin/analyze.sh delete mode 100755 bin/lint.sh delete mode 100755 bin/test.sh delete mode 100755 bin/wally-install.sh create mode 100644 justfile diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md index e44a91be..a2659d2b 100644 --- a/.github/pull_request_template.md +++ b/.github/pull_request_template.md @@ -8,4 +8,4 @@ Describe the solution you came up with # Checklist -- [ ] Ran `./bin/test.sh` locally before merging +- [ ] Ran `just test` locally before merging diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index f52ea618..608776c2 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -12,23 +12,17 @@ jobs: steps: - uses: actions/checkout@v3 + - uses: extractions/setup-just@v1 + - uses: Roblox/setup-foreman@v1 with: token: ${{ secrets.GITHUB_TOKEN }} - - name: Lint - run: | - selene generate-roblox-std - selene src/ - - - name: Format - run: stylua --check src/ + - name: Initialize the project + run: just init - - name: Lint file extensions - run: ./bin/lint.sh - - - name: Install dependencies - run: wally install + - name: Lint + run: just lint - name: Get model file name run: | @@ -49,29 +43,17 @@ jobs: steps: - uses: actions/checkout@v3 + - uses: extractions/setup-just@v1 + - uses: Roblox/setup-foreman@v1 with: token: ${{ secrets.GITHUB_TOKEN }} - - name: Install dependencies - run: ./bin/wally-install.sh + - name: Initialize the project + run: just init - name: Run Luau analysis - run: ./bin/analyze.sh - - scripts: - runs-on: ubuntu-latest - steps: - - uses: actions/checkout@v3 - - - name: Ensure each script is executable - run: | - for f in ./bin/*; do - if [[ ! -x "$f" ]]; then - echo "Script '$f' is not executable" - exit 1 - fi - done + run: just analyze # Running unit tests in CI has historically been cumbersome, and presently # there is no way to run Roblox Studio from a GitHub workflow. As such, our diff --git a/.vscode/extensions.json b/.vscode/extensions.json new file mode 100644 index 00000000..9be45fc2 --- /dev/null +++ b/.vscode/extensions.json @@ -0,0 +1,9 @@ +{ + "recommendations": [ + "evaera.vscode-rojo", + "Kampfkarren.selene-vscode", + "JohnnyMorganz.stylua", + "JohnnyMorganz.luau-lsp", + "EditorConfig.EditorConfig", + ] +} \ No newline at end of file diff --git a/bin/analyze.sh b/bin/analyze.sh deleted file mode 100755 index e452e6d5..00000000 --- a/bin/analyze.sh +++ /dev/null @@ -1,12 +0,0 @@ -#!/usr/bin/env bash - -curl -s -O https://raw.githubusercontent.com/JohnnyMorganz/luau-lsp/master/scripts/globalTypes.d.lua - -rojo sourcemap tests.project.json -o sourcemap.json - -luau-lsp analyze --sourcemap=sourcemap.json --defs=globalTypes.d.lua --defs=testez.d.luau --ignore=**/_Index/** src/ -exit_code=$? - -rm globalTypes.d.lua - -exit $exit_code diff --git a/bin/lint.sh b/bin/lint.sh deleted file mode 100755 index 1ee55d8c..00000000 --- a/bin/lint.sh +++ /dev/null @@ -1,11 +0,0 @@ -#!/usr/bin/env bash - -set -euo pipefail - -echo "Lint file extensions" -files=$(find src example -iname "*.lua") -if [[ -n "$files" ]]; then - echo "Error: one or more files are using the '.lua' extension. Please update these to '.luau' and try again" - echo "$files" - exit 1 -fi diff --git a/bin/test.sh b/bin/test.sh deleted file mode 100755 index 6d48bf3b..00000000 --- a/bin/test.sh +++ /dev/null @@ -1,3 +0,0 @@ -rojo build tests.project.json -o tests.rbxl -run-in-roblox --place tests.rbxl --script tests/init.server.luau -rm tests.rbxl diff --git a/bin/wally-install.sh b/bin/wally-install.sh deleted file mode 100755 index 3e6b7ec5..00000000 --- a/bin/wally-install.sh +++ /dev/null @@ -1,9 +0,0 @@ -#!/usr/bin/env bash - -set -e - -wally install - -rojo sourcemap tests.project.json --output sourcemap.json - -wally-package-types --sourcemap sourcemap.json Packages/ diff --git a/docs/contributing.md b/docs/contributing.md index 0dfc0aca..87bf2221 100644 --- a/docs/contributing.md +++ b/docs/contributing.md @@ -6,55 +6,23 @@ sidebar_position: 5 Thank you for your interest in contributing to this repository! This guide will help you get your environment setup so you can have the best possible development experience. -## Getting Started +## Onboarding -You should be using [Visual Studio Code](https://code.visualstudio.com/) as your text editor, and have the following extensions installed: +We use [Visual Studio Code](https://code.visualstudio.com/) to work on this project, so you'll get the best mileage from using it too. We also have several [recommended extensions](https://github.com/flipbook-labs/flipbook/blob/main/.vscode/extensions.json) that should be installed. -- [Rojo](https://marketplace.visualstudio.com/items?itemName=evaera.vscode-rojo) -- [Selene](https://marketplace.visualstudio.com/items?itemName=Kampfkarren.selene-vscode) -- [StyLua](https://marketplace.visualstudio.com/items?itemName=JohnnyMorganz.stylua) -- [Luau LSP](https://marketplace.visualstudio.com/items?itemName=JohnnyMorganz.luau-lsp) +You will also need [Just](https://github.com/casey/just) for running commands, and [Foreman](https://github.com/Roblox/foreman/) +for installing pinned tool versions. -Once the Rojo extension is installed a welcome screen will be displayed. Scroll down to the section for the Roblox Studio plugin and select "Manage it for me." Next time you open a place in Studio you will have the Rojo plugin ready to go. - -Next install our toolchain manager, [Foreman](https://github.com/Roblox/foreman/). Foreman handles the installation of several of our other tools, like Rojo, Wally, Selene, and StyLua. - -To make the tools that Foreman installs avialable on your system you will need to manually add it to your `PATH`. - -- Windows - - Add `C:\Users\You\.foreman\bin` to your `PATH` - - Follow [this guide](https://www.architectryan.com/2018/03/17/add-to-the-path-on-windows-10/) for how to do that -- MacOS - - Open Terminal - - Open the corresponding file for your terminal - - Bash: `nano ~/.bash_profile` - - ZSH: `nano ~/.zshenv` - - Append `export PATH="$PATH:~/.foreman/bin` to the end of the file - -## Development - -With the above requirements satisfied, run the following commands from your clone of this repository to start developing: +With the above requirements satisfied, run the following commands from your clone of the repo to start developing: ```sh -# Install Rojo, Wally, Selene, StyLua, and others -foreman install +# Install tools and packages that the project depends on +just init -# Install dependencies -wally install +# Build the plugin to Studio +just build ``` -Next use Rojo to build the plugin: - -```sh -# Windows -rojo build dev.project.json -o $LOCALAPPDATA/Roblox/Plugins/flipbook.rbxm - -# MacOS -rojo build dev.project.json -o ~/Documents/Roblox/Plugins/flipbook.rbxm -``` - -You can also run `rojo build` with the `--watch` flag while developing so that the plugin gets rebuilt when changes are made. Once rebuilt, simply reload to a new Baseplate for the changes to take effect. - :::tip When using VSCode, you can press `Ctrl+Shift+B` on Windows or `Cmd+Shift+B` on MacOS to execute the included build task which will build the flipbook plugin for your OS. ::: diff --git a/justfile b/justfile new file mode 100644 index 00000000..e8edec8c --- /dev/null +++ b/justfile @@ -0,0 +1,71 @@ +#!/usr/bin/env just --justfile + +project_name := "flipbook" +plugins_dir := if os_family() == "unix" { + "$HOME/Documents/Roblox/Plugins" +} else { + "$LOCALAPPDATA/Roblox/Plugins" +} +plugin_path := plugins_dir / project_name + ".rbxm" + +project_dir := absolute_path("src") +example_dir := absolute_path("src") +packages_dir := absolute_path("Packages") +tests_project := "tests.project.json" + +tmpdir := `mktemp -d` +global_defs_path := tmpdir / "globalTypes.d.lua" +testez_defs_path := "testez.d.luau" +sourcemap_path := tmpdir / "sourcemap.json" + +_lint-file-extensions: + #!/usr/bin/env bash + set -euo pipefail + files=$(find {{ project_dir }} {{ example_dir }} -iname "*.lua") + if [[ -n "$files" ]]; then + echo "Error: one or more files are using the '.lua' extension. Please update these to '.luau' and try again" + echo "$files" + exit 1 + fi + +default: + @just --list + +wally-install: + wally install + rojo sourcemap {{ tests_project }} -o {{ sourcemap_path }} + wally-package-types --sourcemap {{ sourcemap_path }} {{ packages_dir }} + +init: + foreman install + just wally-install + +lint: + selene {{ project_dir }} + stylua --check {{ project_dir }} + just _lint-file-extensions + +build: + rojo build -o {{ plugin_path }} + +build-watch: + npx -y chokidar-cli "{{ project_dir }}/**/*" --initial \ + -c "just build" \ + +test: + rojo build {{ tests_project }} -o test-place.rbxl + run-in-roblox --place test-place.rbxl --script tests/init.server.lua + +analyze: + curl -s -o {{ global_defs_path }} \ + -O https://raw.githubusercontent.com/JohnnyMorganz/luau-lsp/master/scripts/globalTypes.d.lua + + rojo sourcemap {{ tests_project }} -o {{ sourcemap_path }} + + luau-lsp analyze --sourcemap={{ sourcemap_path }} \ + --defs={{ global_defs_path }} \ + --defs={{ testez_defs_path }} \ + --settings="./.vscode/settings.json" \ + --ignore=**/_Index/** \ + {{ project_dir }} +