Ron Evans
a213d9ae46
* GNUmakefile: split into topic files in make/ The GNUmakefile had 1295 lines and mixed build configuration, LLVM bootstrapping, device generation, four test suites, the smoke tests, release packaging, and lint tools. The smoke tests alone were 500 lines. Move each part into its own file in make/ and include them from GNUmakefile. config.mk must be included first because the other files use its variables in immediate assignments and conditionals. There is no change in behavior. The parsed make database is identical for the default build and for ASSERT=1, STATIC=1, XTENSA=0, STM32=0, WASM=0, and CROSS=aarch64-linux-gnu, except for MAKEFILE_LIST and the .PHONY list, which now also includes targets that were phony but not declared. The Dockerfile copies GNUmakefile alone before it builds LLVM, to keep that layer independent of the source tree. It must copy make/ too. * make/smoketest.mk: split into groups and add smoketest-quick The smoke test was one recipe of about 500 lines with 236 builds that always ran in sequence. Split it at the group boundaries that were already there, so that: - `make -j smoketest` builds the groups in parallel. A full run goes from 325 to 91 seconds on a 32 core machine. - CI can shard the groups across runners. Each group writes to its own name in build/smoke/, because all builds wrote to test.hex before and would overwrite each other in a parallel build. The output extension selects the format, so it stays per line. Add smoketest-quick, which builds one board for each processor architecture. The full smoke test answers "can TinyGo build for every board", which does not depend on the host OS, so it only needs to run on one OS. The other jobs use smoketest-quick. The comment above the esp32c3 group had 4 spaces of indentation instead of a tab. That was harmless in the middle of a recipe, but it is now the first line of a group, where it would stop the recipe from starting. The set of build commands is unchanged for the default flags and for XTENSA=0, STM32=0, and WASM=0. All 226 checksums are the same as before, for a sequential build and for `make -j16`. * ci: run the full smoke test once, on Linux only The smoke test ran six times for each push: twice on Linux, twice on macOS, once on Windows, and once in the compatibility test. Together that was about 97 minutes of the CI time. The smoke test checks that TinyGo can build a binary for each board. That does not depend on the host OS. The only part that does is one build behind a Windows check. Add a smoketest-linux job that runs the full set, split across four runners that use the tarball from the build-linux job. The groups are balanced with the measured build time of each group. Remove the full smoke test from test-linux-build, which the new job replaces, and use smoketest-quick for the other four jobs. Expected result: about 55 to 39 minutes for the slowest workflow, and about 97 to 35 minutes of total smoke test time. * make/smoketest.mk: build nintendoswitch in smoketest-quick It is the only target that uses the aarch64 LLVM triple. With it, smoketest-quick covers all 13 triples that the full smoke test uses.
4.1 KiB
Building TinyGo
TinyGo depends on LLVM and libclang, which are both big C++ libraries. It can
also optionally use a built-in lld to ease cross compiling. There are two ways
these can be linked: dynamically and statically. An install with go install is
dynamic linking because it is fast and works almost out of the box on
Debian-based systems with the right packages installed.
This guide describes how to statically link TinyGo against LLVM, libclang and lld so that the binary can be easily moved between systems. It also shows how to build a release tarball that includes this binary and all necessary extra files.
Note: this documentation describes how to build a statically linked release tarball. If you want to help with development of TinyGo itself, you should follow the guide located at https://tinygo.org/docs/guides/build/
Dependencies
LLVM, Clang and LLD are quite light on dependencies, requiring only standard build tools to be built. Go is of course necessary to build TinyGo itself.
- Go (1.19+)
- GNU Make
- Standard build tools (gcc/clang)
- git
- CMake
- Ninja
The rest of this guide assumes you're running Linux, but it should be equivalent on a different system like Mac.
Using GNU Make
The static build of TinyGo is driven by GNUmakefile, which includes the topic
files in the make/ directory (config.mk, llvm.mk, gen-device.mk,
build.mk, test.mk, smoketest.mk, release.mk, and tools.mk).
It provides a help target for quick reference:
% make help
clean Remove build directory
fmt Reformat source
fmt-check Warn if any source needs reformatting
gen-device Generate microcontroller-specific sources
llvm-source Get LLVM sources
llvm-build Build LLVM
tinygo Build the TinyGo compiler
lint Lint source tree
spell Spellcheck source tree
Download the source
The first step is to download the TinyGo sources (use --recursive if you clone
the git repository). Then, inside the directory, download the LLVM source:
make llvm-source
You can also store LLVM outside of the TinyGo root directory by setting the
LLVM_BUILDDIR, CLANG_SRC and LLD_SRC make variables, but that is not
covered by this guide.
Build LLVM, Clang, LLD
Before starting the build, you may want to set the following environment variables to speed up the build. Most Linux distributions ship with GCC as the default compiler, but Clang is significantly faster and uses much less memory while producing binaries that are about as fast.
export CC=clang
export CXX=clang++
make/config.mk holds a default configuration that is good for most users. It
builds a release version of LLVM (optimized, no asserts) and includes all
targets supported by TinyGo:
make llvm-build
This can take over an hour depending on the speed of your system.
Build TinyGo
The last step of course is to build TinyGo itself. This can again be done with make:
make
Verify TinyGo
Try running TinyGo:
./build/tinygo help
Also, make sure the tinygo binary really is statically linked. The command to check for
dynamic dependencies differs depending on your operating system.
On Linux, use ldd (not to be confused with lld):
ldd ./build/tinygo
On macOS, use otool -L:
otool -L ./build/tinygo
The result should not contain libclang or libLLVM.
Make a release tarball
Now that we have a working static build, it's time to make a release tarball:
make release
If you did not clone the repository with the --recursive option, you will get errors until you initialize the project submodules:
git submodule update --init
The release tarball is stored in build/release.tar.gz, and can be extracted with the following command (for example in ~/lib):
tar -xvf path/to/release.tar.gz
TinyGo will get extracted to a tinygo directory. You can then call it with:
./tinygo/bin/tinygo