blender/flamenco
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Website: document the use of build tool mage

Browse Source
This commit is contained in:
Sybren A. Stüvel 2024-10-04 22:47:29 +02:00
parent 4ae4b892fd
commit 7d8262e630
2 changed files with 82 additions and 27 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

64
web/project-website/content/development/building/_index.md
View File

@ -7,19 +7,73 @@ 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. |
@ -30,5 +84,3 @@ These `make` targets are available:
| `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

11
web/project-website/content/development/getting-started/_index.md
View File

@ -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/" >}}