github.com/0xKiwi/rules_go@v0.24.3/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      load("@bazel_tools//tools/build_defs/repo:git.bzl", "git_repository")
    70  
    71      git_repository(
    72          name = "rules_cc",
    73          commit = "7e650b11fe6d49f70f2ca7a1c4cb8bcc4a1fe239",
    74          remote = "https://github.com/bazelbuild/rules_cc",
    75          shallow_since = "1578064657 -0800",
    76      )
    77  
    78      -- BUILD.bazel --
    79      load("@rules_cc//cc:defs.bzl", "cc_binary")
    80  
    81      cc_binary(
    82          name = "hello",
    83          srcs = ["hello.c"],
    84      )
    85  
    86      -- hello.c --
    87      #include <stdio.h>
    88  
    89      int main() {
    90        printf("hello\n");
    91        return 0;
    92      }
    93  
    94  To build with MinGW, run the command below. Add the ``-s`` flag to print
    95  commands executed by Bazel to confirm MinGW is actually used.
    96  
    97  .. code::
    98  
    99      bazel build --cpu=x64_windows --compiler=mingw-gcc //:hello
   100  
   101  Future versions of Bazel will select a C/C++ toolchain using the same platform
   102  and toolchain system used by other rules. This will be the default after the
   103  `--incompatible_enable_cc_toolchain_resolution`_ flag is flipped. To ensure
   104  that the MinGW toolchain is registered, either build against a ``platform``
   105  target with the ``@bazel_tools//tools/cpp:mingw`` constraint such as
   106  ``@io_bazel_rules_go//go/toolchain:windows_amd64_cgo``, or define your own
   107  target explicitly, as below:
   108  
   109  .. code::
   110  
   111      platform(
   112          name = "windows_amd64_mingw",
   113          constraint_values = [
   114              "@bazel_tools//tools/cpp:mingw",
   115              "@platforms//cpu:x86_64",
   116              "@platforms//os:windows",
   117          ],
   118      )
   119  
   120  You can build with the command below. This also ensures the MinGW toolchain is
   121  registered (it is not, by default).
   122  
   123  .. code::
   124  
   125      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
   126  
   127  You may want to add these flags to a ``.bazelrc`` file in your project root
   128  directory or in your home directory.
   129  
   130  .. code::
   131  
   132      build --cpu=x64_windows
   133      build --compiler=mingw-gcc
   134      build --extra_toolchains=@local_config_cc//:cc-toolchain-x64_windows_mingw
   135      build --host_platform=//:windows_amd64_mingw
   136      build --platforms=//:windows_amd64_mingw
   137      build --incompatible_enable_cc_toolchain_resolution
   138  
   139  Confirm Go works
   140  ----------------
   141  
   142  * Copy boilerplate from rules_go.
   143  * Confirm that you can run a pure Go "hello world" binary with
   144    ``bazel run //:target``
   145  * Confirm you can run a cgo binary with the same set of flags and platforms
   146    used to build a C target above.