1Using 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
7This document provides a list of instructions for setting up Bazel to build
8Go code on a Windows computer.
9
10Most of the difficulty here is installing a compatible C/C++ toolchain. Cgo
11only works with GCC and clang toolchains, so MSVC cannot be used. This is a
12Go limitation, not a Bazel or rules_go problem: cgo determines types of
13definitions by parsing error messages that GCC emits when compiling generated
14files.
15
16See also `Installing Bazel on Windows`_, the official instructions for
17installing Bazel.
18
19Install 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
53Install 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
61Confirm C/C++ works
62-------------------
63
64Create 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
84To build with MinGW, run the command below. Add the ``-s`` flag to print
85commands executed by Bazel to confirm MinGW is actually used.
86
87.. code::
88
89 bazel build --cpu=x64_windows --compiler=mingw-gcc //:hello
90
91Future versions of Bazel will select a C/C++ toolchain using the same platform
92and toolchain system used by other rules. This will be the default after the
93`--incompatible_enable_cc_toolchain_resolution`_ flag is flipped. To ensure
94that the MinGW toolchain is registered, either build against a ``platform``
95target with the ``@bazel_tools//tools/cpp:mingw`` constraint such as
96``@io_bazel_rules_go//go/toolchain:windows_amd64_cgo``, or define your own
97target 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
110You can build with the command below. This also ensures the MinGW toolchain is
111registered (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
117You may want to add these flags to a ``.bazelrc`` file in your project root
118directory 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
129Confirm 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.
View as plain text