github.com/tinygo-org/tinygo@v0.31.3-0.20240404173401-90b0bf646c27/BUILDING.md (about)

     1  # Building TinyGo
     2  
     3  TinyGo depends on LLVM and libclang, which are both big C++ libraries. It can
     4  also optionally use a built-in lld to ease cross compiling. There are two ways
     5  these can be linked: dynamically and statically. An install with `go install` is
     6  dynamic linking because it is fast and works almost out of the box on
     7  Debian-based systems with the right packages installed.
     8  
     9  This guide describes how to statically link TinyGo against LLVM, libclang and
    10  lld so that the binary can be easily moved between systems. It also shows how to
    11  build a release tarball that includes this binary and all necessary extra files.
    12  
    13  **Note**: this documentation describes how to build a statically linked release
    14  tarball. If you want to help with development of TinyGo itself, you should follow the guide located at https://tinygo.org/docs/guides/build/
    15  
    16  ## Dependencies
    17  
    18  LLVM, Clang and LLD are quite light on dependencies, requiring only standard
    19  build tools to be built. Go is of course necessary to build TinyGo itself.
    20  
    21    * Go (1.18+)
    22    * GNU Make
    23    * Standard build tools (gcc/clang)
    24    * git
    25    * CMake
    26    * [Ninja](https://ninja-build.org/)
    27  
    28  The rest of this guide assumes you're running Linux, but it should be equivalent
    29  on a different system like Mac.
    30  
    31  ## Download the source
    32  
    33  The first step is to download the TinyGo sources (use `--recursive` if you clone
    34  the git repository). Then, inside the directory, download the LLVM source:
    35  
    36      make llvm-source
    37  
    38  You can also store LLVM outside of the TinyGo root directory by setting the
    39  `LLVM_BUILDDIR`, `CLANG_SRC` and `LLD_SRC` make variables, but that is not
    40  covered by this guide.
    41  
    42  ## Build LLVM, Clang, LLD
    43  
    44  Before starting the build, you may want to set the following environment
    45  variables to speed up the build. Most Linux distributions ship with GCC as the
    46  default compiler, but Clang is significantly faster and uses much less memory
    47  while producing binaries that are about as fast.
    48  
    49      export CC=clang
    50      export CXX=clang++
    51  
    52  The Makefile includes a default configuration that is good for most users. It
    53  builds a release version of LLVM (optimized, no asserts) and includes all
    54  targets supported by TinyGo:
    55  
    56      make llvm-build
    57  
    58  This can take over an hour depending on the speed of your system.
    59  
    60  ## Build TinyGo
    61  
    62  The last step of course is to build TinyGo itself. This can again be done with
    63  make:
    64  
    65      make
    66  
    67  ## Verify TinyGo
    68  
    69  Try running TinyGo:
    70  
    71      ./build/tinygo help
    72  
    73  Also, make sure the `tinygo` binary really is statically linked. Check this
    74  using `ldd` (not to be confused with `lld`):
    75  
    76      ldd ./build/tinygo
    77  
    78  The result should not contain libclang or libLLVM.
    79  
    80  ## Make a release tarball
    81  
    82  Now that we have a working static build, it's time to make a release tarball:
    83  
    84      make release
    85  
    86  If you did not clone the repository with the `--recursive` option, you will get errors until you initialize the project submodules:
    87  
    88      git submodule update --init
    89  
    90  The release tarball is stored in build/release.tar.gz, and can be extracted with
    91  the following command (for example in ~/lib):
    92  
    93      tar -xvf path/to/release.tar.gz
    94  
    95  TinyGo will get extracted to a `tinygo` directory. You can then call it with:
    96  
    97      ./tinygo/bin/tinygo