diff --git a/web/project-website/content/development/building/_index.md b/web/project-website/content/development/building/_index.md index cbc51079..3cbb3aa0 100644 --- a/web/project-website/content/development/building/_index.md +++ b/web/project-website/content/development/building/_index.md @@ -7,28 +7,80 @@ For the steps towards your first build, see [Getting Started][start]. [start]: {{< relref "../getting-started ">}} +## Building with Magefile + +The Flamenco build tool is made in Go, using [Magefile][mage]. + +[mage]: https://magefile.org/ + +### Basic Builds + +```sh +$ go run mage.go build +``` + +This builds Flamenco Manager, including its webapp, and Flamenco Worker. + +### Listing Build Targets + +``` +$ go run mage.go -l +Targets: + build Flamenco Manager and Flamenco Worker, including the webapp and the add-on + check Run unit tests, check for vulnerabilities, and run the linter + clean Remove executables and other build output + devServerWebapp + flamencoManager Build Flamenco Manager with the webapp and add-on ZIP embedded + flamencoManagerWithoutWebapp Only build the Flamenco Manager executable, do not rebuild the webapp + flamencoWorker Build the Flamenco Worker executable + generate code (OpenAPI and test mocks) + generateGo Generate Go code for Flamenco Manager and Worker + generateJS Generate JavaScript code for the webapp + generatePy Generate Python code for the add-on + govulncheck Check for known vulnerabilities. + installDeps Install build-time dependencies: code generators and NodeJS dependencies. + installDepsWebapp Use Yarn to install the webapp's NodeJS dependencies + installGenerators Install code generators. + staticcheck Analyse the source code. + test Run unit tests + version Show which version information would be embedded in executables + vet Run `go vet` + webappStatic Build the webapp as static files that can be served +``` + +### Faster Re-builds + +The above commands first build the build tool itself, and then run it. The build +tool can also be compiled once, and then used as any other program: + +```sh +$ go run mage.go -compile mage +$ ./magefiles/mage build +``` + +### Building with `make` + +`make` can be used as a convenient front-end for the Magefile build tool. A few +targets are available with `make` only. These are mostly for release-related +functionality like updating the Flamenco version, or building release packages. + These `make` targets are available: -| Target | Description | -|-----------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| `application` | Builds Flamenco Manager, Worker, and the development version of the webapp. This is the default target when just running `make` | -| `flamenco-manager` | Builds just Flamenco Manager. This includes packing the webapp and the Blender add-on into the executable. | -| `flamenco-worker` | Builds just Flamenco Worker. | -| `flamenco-manager_race` | Builds Flamenco Manager with the [data race detector][race] enabled. As this is for development only, this does not include packing the webapp and the Blender add-on into the executable. | -| `flamenco-manager-without-webapp` | Builds Flamenco Manager without rebuilding the webapp. This is useful to speed up the build when you're using the webapp development server (see below) | -| `flamenco-worker_race` | Builds Flamenco Worker with the [data race detector][race] enabled. | -| `webapp` | Installs the webapp dependencies, so that the development server can be run with `yarn --cwd web/app run dev --host` | -| `webapp-static` | Builds the webapp so that it can be served as static files by Flamenco Manager. | -| `addon-packer` | Builds the addon packer. This is a little Go tool that creates the Blender add-on ZIP file. Typically this target isn't used directly; the other Makefile targets depend on it. | -| `generate` | Generate the Go, Python, and JavaScript code. | -| `generate-go` | Generate the Go code, which includes OpenAPI code, as well as mocks for the unit tests. | -| `generate-py` | Generate the Python code, containing the OpenAPI client code for the Blender add-on. | -| `generate-js` | Generate the JavaScript code, containing the OpenAPI client code for the web interface. | -| `test` | Run the unit tests. | -| `clean` | Remove build-time files. | -| `version` | Print some version numbers, mostly for debugging the Makefile itself. | -| `list-embedded` | List the files embedded into the `flamenco-manager` executable. | -| `tools` | Download FFmpeg for all supported platforms. Can be suffixed by `-linux`, `-windows`, or `-darwin` to only download for specific platforms. | -| `release-package` | Builds release packages for all supported platforms. Can be suffixed by `-linux`, `-windows`, or `-darwin` to only build specific platforms. | - -[race]: https://go.dev/doc/articles/race_detector +| Target | Description | +|-----------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------| +| `application` | Builds Flamenco Manager, Worker, and the development version of the webapp. This is the default target when just running `make` | +| `flamenco-manager` | Builds just Flamenco Manager. This includes packing the webapp and the Blender add-on into the executable. | +| `flamenco-worker` | Builds just Flamenco Worker. | +| `flamenco-manager-without-webapp` | Builds Flamenco Manager without rebuilding the webapp. This is useful to speed up the build when you're using the webapp development server (see below) | +| `webapp` | Installs the webapp dependencies, so that the development server can be run with `yarn --cwd web/app run dev --host` | +| `webapp-static` | Builds the webapp so that it can be served as static files by Flamenco Manager. | +| `generate` | Generate the Go, Python, and JavaScript code. | +| `generate-go` | Generate the Go code, which includes OpenAPI code, as well as mocks for the unit tests. | +| `generate-py` | Generate the Python code, containing the OpenAPI client code for the Blender add-on. | +| `generate-js` | Generate the JavaScript code, containing the OpenAPI client code for the web interface. | +| `test` | Run the unit tests. | +| `clean` | Remove build-time files. | +| `version` | Print some version numbers, mostly for debugging the Makefile itself. | +| `list-embedded` | List the files embedded into the `flamenco-manager` executable. | +| `tools` | Download FFmpeg for all supported platforms. Can be suffixed by `-linux`, `-windows`, or `-darwin` to only download for specific platforms. | +| `release-package` | Builds release packages for all supported platforms. Can be suffixed by `-linux`, `-windows`, or `-darwin` to only build specific platforms. | diff --git a/web/project-website/content/development/getting-started/_index.md b/web/project-website/content/development/getting-started/_index.md index 3bdc01cd..a85eda03 100644 --- a/web/project-website/content/development/getting-started/_index.md +++ b/web/project-website/content/development/getting-started/_index.md @@ -112,14 +112,17 @@ TODO: write this documentation. ## 4. Your First Build -Run `make with-deps` to install build-time dependencies and build the application. -Subsequent builds can just run `make` without arguments. +Run `go run mage.go installDeps` to install build-time dependencies. This is +only necessary the first time you build Flamenco (or when these dependencies are +upgraded, which is rare) + +Build the application with `go run mage.go build`. You should now have two executables: `flamenco-manager` and `flamenco-worker`. Both can be run with the `-help` CLI argument to see the available options. -See [building][building] for more `make` targets, for example to run unit tests, -enable the race condition checker, and all other kinds of useful things. +See [building][building] for more `mage` targets, for example to run unit tests, +enable the race condition checker, and ways to speed up the build process. [building]: {{< relref "../building/" >}}