github.com/bazelbuild/rules_go@v0.47.2-0.20240515105122-e7ddb9ea474e/windows.rst (about)

     1  Using rules_go on Windows
     2  =========================
     3  
     4  .. _--incompatible_enable_cc_toolchain_resolution: https://github.com/bazelbuild/bazel/issues/7260
     5  .. _Installing Bazel on Windows: https://docs.bazel.build/versions/master/install-windows.html
     6  
     7  This document provides a list of instructions for setting up Bazel to build
     8  Go code on a Windows computer.
     9  
    10  Most of the difficulty here is installing a compatible C/C++ toolchain. Cgo
    11  only works with GCC and clang toolchains, so MSVC cannot be used. This is a
    12  Go limitation, not a Bazel or rules_go problem: cgo determines types of
    13  definitions by parsing error messages that GCC emits when compiling generated
    14  files.
    15  
    16  See also `Installing Bazel on Windows`_, the official instructions for
    17  installing Bazel.
    18  
    19  Install and configure dependencies
    20  ----------------------------------
    21  
    22  * Install msys2 from https://www.msys2.org/. This is needed to provide a bash
    23    environment for Bazel.
    24  
    25    * Follow the installation directions to the end, including
    26      running ``pacman -Syu`` and ``pacman -Su`` in the msys2 shell.
    27  
    28  * Install additional msys2 tools.
    29  
    30    * Run ``pacman -S mingw-w64-x86_64-gcc``. GCC is needed if you plan to build
    31      any cgo code. MSVC will not work with cgo. This is a Go limitation, not a
    32      Bazel limitation. cgo determines types of definitions by compiling specially
    33      crafted C files and parsing error messages. GCC or clang are specifically
    34      needed for this.
    35    * Run ``pacman -S patch``. ``patch`` is needed by ``git_repository`` and
    36      ``http_archive`` dependencies declared by rules_go. We use it to add
    37      and modify build files.
    38  
    39  * Add ``C:\msys64\usr\bin`` to ``PATH`` in order to locate ``patch`` and
    40    other DLLs.
    41  * Add ``C:\msys64\mingw64\bin`` to ``PATH`` in order to locate mingw DLLs.
    42    ``protoc`` and other host binaries will not run without these.
    43  * Set the environment variable ``BAZEL_SH`` to ``C:\msys64\usr\bin\bash.exe``.
    44    Bazel needs this to run shell scripts.
    45  * Set the environment variable ``CC`` to ``C:\msys64\mingw64\bin\gcc.exe``.
    46    Bazel uses this to configure the C/C++ toolchain.
    47  * Install the MSVC++ redistributable from
    48    https://www.microsoft.com/en-us/download/details.aspx?id=48145.
    49    Bazel itself depends on this.
    50  * Install Git from https://git-scm.com/download/win. The Git install should
    51    add the installed directory to your ``PATH`` automatically.
    52  
    53  Install bazel
    54  -------------
    55  
    56  * Download Bazel from https://github.com/bazelbuild/bazel/releases.
    57  * Move the binary to ``%APPDATA%\bin\bazel.exe``.
    58  * Add that directory to ``PATH``.
    59  * Confirm ``bazel version`` works.
    60  
    61  Confirm C/C++ works
    62  -------------------
    63  
    64  Create a workspace with a simple ``cc_binary`` target.
    65  
    66  .. code::
    67  
    68      -- WORKSPACE --
    69  
    70      -- BUILD.bazel --
    71      cc_binary(
    72          name = "hello",
    73          srcs = ["hello.c"],
    74      )
    75  
    76      -- hello.c --
    77      #include <stdio.h>
    78  
    79      int main() {
    80        printf("hello\n");
    81        return 0;
    82      }
    83  
    84  To build with MinGW, run the command below. Add the ``-s`` flag to print
    85  commands executed by Bazel to confirm MinGW is actually used.
    86  
    87  .. code::
    88  
    89      bazel build --cpu=x64_windows --compiler=mingw-gcc //:hello
    90  
    91  Future versions of Bazel will select a C/C++ toolchain using the same platform
    92  and toolchain system used by other rules. This will be the default after the
    93  `--incompatible_enable_cc_toolchain_resolution`_ flag is flipped. To ensure
    94  that the MinGW toolchain is registered, either build against a ``platform``
    95  target with the ``@bazel_tools//tools/cpp:mingw`` constraint such as
    96  ``@io_bazel_rules_go//go/toolchain:windows_amd64_cgo``, or define your own
    97  target explicitly, as below:
    98  
    99  .. code::
   100  
   101      platform(
   102          name = "windows_amd64_mingw",
   103          constraint_values = [
   104              "@bazel_tools//tools/cpp:mingw",
   105              "@platforms//cpu:x86_64",
   106              "@platforms//os:windows",
   107          ],
   108      )
   109  
   110  You can build with the command below. This also ensures the MinGW toolchain is
   111  registered (it is not, by default).
   112  
   113  .. code::
   114  
   115      bazel build --extra_toolchains=@local_config_cc//:cc-toolchain-x64_windows_mingw --host_platform=//:windows_amd64_mingw --platforms=//:windows_amd64_mingw --incompatible_enable_cc_toolchain_resolution //:hello
   116  
   117  You may want to add these flags to a ``.bazelrc`` file in your project root
   118  directory or in your home directory.
   119  
   120  .. code::
   121  
   122      build --cpu=x64_windows
   123      build --compiler=mingw-gcc
   124      build --extra_toolchains=@local_config_cc//:cc-toolchain-x64_windows_mingw
   125      build --host_platform=//:windows_amd64_mingw
   126      build --platforms=//:windows_amd64_mingw
   127      build --incompatible_enable_cc_toolchain_resolution
   128  
   129  Confirm Go works
   130  ----------------
   131  
   132  * Copy boilerplate from rules_go.
   133  * Confirm that you can run a pure Go "hello world" binary with
   134    ``bazel run //:target``
   135  * Confirm you can run a cgo binary with the same set of flags and platforms
   136    used to build a C target above.