1 | .. SPDX-License-Identifier: CC-BY-SA-4.0 |
---|
2 | |
---|
3 | .. Copyright (C) 2016 Chris Johns <chrisj@rtems.org> |
---|
4 | |
---|
5 | .. _microsoft-windows: |
---|
6 | |
---|
7 | Microsoft Windows |
---|
8 | ================= |
---|
9 | |
---|
10 | RTEMS supports Windows as a development host and the tools for most |
---|
11 | architectures are available. The RTEMS Project relies on the GNU tools for |
---|
12 | compilers and debuggers and we use the simulators that come with GDB and |
---|
13 | QEMU. The Windows support for these tools varies and the RTEMS Project is |
---|
14 | committed to helping the open source community improve the Windows |
---|
15 | experience. If something is not working or supported please email the |
---|
16 | :r:list:`users`. |
---|
17 | |
---|
18 | The RTEMS Project's Windows tools can be native Windows executables |
---|
19 | which give the user the best possible experience on Windows. Native |
---|
20 | Windows programs use the standard Windows DLLs and paths. Integration |
---|
21 | with standard Windows integrated development tools such as editors is |
---|
22 | straight forward. POSIX emulation environments such as Cygwin and the |
---|
23 | MSYS2 shell have special executables that require a POSIX emulation DLL |
---|
24 | and these emulation DLLs add an extra layer of complexity as well as a |
---|
25 | performance over-head. The RTEMS Project uses these POSIX emulation shells |
---|
26 | to run configure scripts that come with various open source packages such |
---|
27 | as `gcc` so they form an important and valued part of the environment we |
---|
28 | describe here. The output of this procedure forms the tools you use during |
---|
29 | your application development and they do not depend on the emulation DLLs. |
---|
30 | |
---|
31 | The performance of a native Windows compiler is as good as you can have |
---|
32 | on Windows and the performance compiling a single file will be similar to |
---|
33 | that on a host like Linux or FreeBSD given the same hardware. Building |
---|
34 | the tools from source is much slower on Windows because POSIX shells |
---|
35 | and related tools are used and the POSIX emulation overhead it much much |
---|
36 | slower than a native POSIX operating system like Linux and FreeBSD. This |
---|
37 | overhead is only during the building of the tools and the RTEMS kernel |
---|
38 | and if you use a suitable build system that is native to Windows your |
---|
39 | application development should be similar to other operating systems. |
---|
40 | |
---|
41 | Building is known to work on `Windows 7 64bit Professional` and |
---|
42 | `Windows 10 64bit`. |
---|
43 | |
---|
44 | .. _windows-path-length: |
---|
45 | |
---|
46 | Windows Path Length |
---|
47 | ------------------- |
---|
48 | |
---|
49 | Windows path length is limited and can cause problems when building the |
---|
50 | tools. The standard Windows API has a ``MAX_PATH`` length of 260 |
---|
51 | characters. This can effect some of the tools used by RTEMS. It is recommended |
---|
52 | you keep the top level directories as short as possible when building the RTEMS |
---|
53 | tools and you should also keep an eye on the path length when developing your |
---|
54 | application. The RTEMS built tools can handle much longer path lengths however |
---|
55 | some of the GNU tools such as those in the ``binutils`` package cannot. |
---|
56 | |
---|
57 | The release packages of the RSB when unpacked have top level file names that |
---|
58 | are too big to build RTEMS. You need to change or rename that path to something |
---|
59 | smaller to build. This is indicated in :ref:`released-version`. |
---|
60 | |
---|
61 | .. _windows-spaces-in-paths: |
---|
62 | |
---|
63 | Windows Spaces In Paths |
---|
64 | ----------------------- |
---|
65 | |
---|
66 | Occasionally, a program will fail on Windows with errors that |
---|
67 | appear as if a directory or file name was partially parsed by |
---|
68 | some utility or program. This can be caused by having directories |
---|
69 | of file names with spaces. Programs written in scripting languages |
---|
70 | sometimes fail to properly quote file names and the space is |
---|
71 | incorrectly interpreted. |
---|
72 | |
---|
73 | Parts of the PATH inherited from the native Windows environment often |
---|
74 | include directory names with spaces. Sometimes it is necessary to set |
---|
75 | the PATH explicitly to avoid these. |
---|
76 | |
---|
77 | .. _msys2_parallel_builds: |
---|
78 | |
---|
79 | Parallel Builds with Make |
---|
80 | ------------------------- |
---|
81 | |
---|
82 | The MSYS2 GNU ``make`` has problems when using the `jobs` option. The RSB |
---|
83 | defaults to automatically using as many cores as the host machine has. To get a |
---|
84 | successful build on Windows it is recommended you add the ``--jobs=none`` |
---|
85 | option to all RSB build set commands. |
---|
86 | |
---|
87 | POSIX Support |
---|
88 | ------------- |
---|
89 | |
---|
90 | Building the RTEMS compilers, debugger, the RTEMS kernel and a number of other |
---|
91 | third-party packages requires a POSIX environment. On Windows you can use Cygwin |
---|
92 | or MSYS2. This document focuses on MSYS2. It is smaller than Cygwin and comes |
---|
93 | with the Arch Linux package manager ``pacman``. |
---|
94 | |
---|
95 | MSYS2 provides MinGW64 support as well as a POSIX shell called MSYS2. The |
---|
96 | MinGW64 compiler and related tools produce 64bit native Windows |
---|
97 | executables. The shell is a standard Bourne shell and the MSYS2 environment is |
---|
98 | a stripped Cygwin shell with enough support to run the various ``configure`` |
---|
99 | scripts needed to build the RTEMS tools and the RTEMS kernel. |
---|
100 | |
---|
101 | MSYS2 is built around the ``pacman`` packaging tool. This makes MSYS2 a |
---|
102 | distribution and that is a welcome feature on Windows. You get a powerful tool |
---|
103 | to manage your development environment on Windows. |
---|
104 | |
---|
105 | Python |
---|
106 | ------ |
---|
107 | |
---|
108 | We need Python to build the tools as the RSB is written in Python and we need |
---|
109 | suitable Python libraries to link to GDB as RTEMS makes use of GDB's Python |
---|
110 | support. This places specific demands on the Python we need installed and |
---|
111 | available and MSYS2 provides suitable Python versions we can use. You need to |
---|
112 | make sure you have the correct type and version of Python installed. |
---|
113 | |
---|
114 | We cannot use the Python executables created by the Python project (python.org) |
---|
115 | as they are built by Microsoft's C (MSC) compiler. Linking the MSC Python |
---|
116 | libraries with the MinGW64 executables is not easy and MSYS provides us with a |
---|
117 | simple solution so we do not support linking MSC libraries. |
---|
118 | |
---|
119 | MSYS2 provides two types and two versions of Python executables, MinGW and MSYS |
---|
120 | and Python version 2 and 3. For Windows we need the MinGW executable so we have |
---|
121 | suitables libraries and we have to have Python version 2 because on Windows GDB |
---|
122 | only builds with Python2. |
---|
123 | |
---|
124 | You also need to install the MSYS version of Python along with the MinGW64 |
---|
125 | Python2 package. The MSYS Python is version 3 and the RSB can support version 2 |
---|
126 | and 3 of Python and it helps handle some of the long paths building GCC can |
---|
127 | generate. |
---|
128 | |
---|
129 | .. _microsoft-windows-installation: |
---|
130 | |
---|
131 | MSYS2 |
---|
132 | ----- |
---|
133 | |
---|
134 | MSYS2 is installed on a new machine using the MSYS2 installer found on |
---|
135 | https://msys2.github.io/. Please select the ``x86_64`` variant for 64bit |
---|
136 | support. Run the installer following the 7 steps listed on the page. |
---|
137 | |
---|
138 | MSYS2 uses the ``pacman`` package manager. The Arch Linux project has detailed |
---|
139 | documentation on how to use ``pacman``. What is shown here is a just few |
---|
140 | examples of what you can do. |
---|
141 | |
---|
142 | .. sidebar:: **Pin MSYS2 Shell to Taskbar** |
---|
143 | |
---|
144 | Pin the MSYS2 64bit Shell to the Taskbar so you always use it rather than the |
---|
145 | 32bit Shell. |
---|
146 | |
---|
147 | Open a 64bit MSYS shell from the Start Menu: |
---|
148 | |
---|
149 | .. figure:: ../../images/msys2-minw64-start-menu.png |
---|
150 | :width: 50% |
---|
151 | :align: center |
---|
152 | :alt: MSYS2 64bit Shell Start Menu |
---|
153 | |
---|
154 | The packages we require are: |
---|
155 | |
---|
156 | * python |
---|
157 | * mingw-w64-x86_64-python2 |
---|
158 | * mingw-w64-x86_64-gcc |
---|
159 | * git |
---|
160 | * bison |
---|
161 | * cvs |
---|
162 | * diffutils |
---|
163 | * make |
---|
164 | * patch |
---|
165 | * tar |
---|
166 | * texinfo |
---|
167 | * unzip |
---|
168 | |
---|
169 | .. note:: |
---|
170 | |
---|
171 | The actual output provided may vary due to changes in the dependent packages |
---|
172 | or newer package versions. |
---|
173 | |
---|
174 | Install the packages using ``pacman``: |
---|
175 | |
---|
176 | .. code-block:: none |
---|
177 | |
---|
178 | $ pacman -S python mingw-w64-x86_64-python2 mingw-w64-x86_64-gcc \ |
---|
179 | bison cvs diffutils git make patch tar texinfo unzip |
---|
180 | resolving dependencies... |
---|
181 | looking for conflicting packages... |
---|
182 | .... output shortened for brevity .... |
---|
183 | |
---|
184 | .. _Cygwin: |
---|
185 | |
---|
186 | Cygwin |
---|
187 | ------ |
---|
188 | |
---|
189 | Building on Windows is a little more complicated because the Cygwin shell is |
---|
190 | used rather than the MSYS2 shell. The MSYS2 shell is simpler because the |
---|
191 | detected host triple is MinGW so the build is a standard cross-compiler build. |
---|
192 | A Canadian cross-build using Cygwin is supported if you would like native |
---|
193 | tools or you can use a Cygwin built set of tools. |
---|
194 | |
---|
195 | Install a recent Cygwin version using the Cygwin setup tool. Select and install |
---|
196 | the groups and packages listed: |
---|
197 | |
---|
198 | .. table:: Cygwin Packages |
---|
199 | |
---|
200 | ======= ========================= |
---|
201 | Group Package |
---|
202 | Archive bsdtar |
---|
203 | Archive unzip |
---|
204 | Archive xz |
---|
205 | Devel autoconf |
---|
206 | Devel autoconf2.1 |
---|
207 | Devel autoconf2.5 |
---|
208 | Devel automake |
---|
209 | Devel binutils |
---|
210 | Devel bison |
---|
211 | Devel flex |
---|
212 | Devel gcc4-core |
---|
213 | Devel gcc4-g++ |
---|
214 | Devel git |
---|
215 | Devel make |
---|
216 | Devel mingw64-x86_64-binutils |
---|
217 | Devel mingw64-x86_64-gcc-core |
---|
218 | Devel mingw64-x86_64-g++ |
---|
219 | Devel mingw64-x86_64-runtime |
---|
220 | Devel mingw64-x86_64-zlib |
---|
221 | Devel patch |
---|
222 | Devel zlib-devel |
---|
223 | MinGW mingw-zlib-devel |
---|
224 | Python python |
---|
225 | ======= ========================= |
---|
226 | |
---|
227 | The setup tool will add a number of dependent package and it is ok to accept |
---|
228 | them. |
---|
229 | |
---|
230 | Disabling Windows Defender improves performance if you have another up to date |
---|
231 | virus detection tool installed and enabled. The excellent ``Process Hacker 2`` |
---|
232 | tool can monitor the performance and the Windows Defender service contributed a |
---|
233 | high load. In this case a third-party virus tool was installed so the Windows |
---|
234 | Defender service was not needed. |
---|
235 | |
---|
236 | To build a MinGW tool chain a Canadian cross-compile (Cxc) is required on |
---|
237 | Cygwin because the host is Cygwin therefore a traditional cross-compile will |
---|
238 | result in Cygiwn binaries. With a Canadian cross-compile a Cygwin |
---|
239 | cross-compiler is built as well as the MinGW RTEMS cross-compiler. The Cygwin |
---|
240 | cross-compiler is required to build the C runtime for the RTEMS target because |
---|
241 | we are building under Cygiwn. The build output for an RTEMS 4.10 ARM tool set |
---|
242 | is: |
---|
243 | |
---|
244 | .. code-block:: none |
---|
245 | |
---|
246 | chris@cygwin ~/development/rtems/src/rtems-source-builder/rtems |
---|
247 | $ ../source-builder/sb-set-builder --log=l-arm.txt \ |
---|
248 | --prefix=$HOME/development/rtems/4.10 4.10/rtems-arm |
---|
249 | RTEMS Source Builder - Set Builder, v0.2 |
---|
250 | Build Set: 4.10/rtems-arm |
---|
251 | config: expat-2.1.0-1.cfg |
---|
252 | package: expat-2.1.0-x86_64-w64-mingw32-1 |
---|
253 | building: expat-2.1.0-x86_64-w64-mingw32-1 |
---|
254 | reporting: expat-2.1.0-1.cfg -> expat-2.1.0-x86_64-w64-mingw32-1.html |
---|
255 | config: tools/rtems-binutils-2.20.1-1.cfg |
---|
256 | package: arm-rtems4.10-binutils-2.20.1-1 <1> |
---|
257 | building: arm-rtems4.10-binutils-2.20.1-1 |
---|
258 | package: (Cxc) arm-rtems4.10-binutils-2.20.1-1 <2> |
---|
259 | building: (Cxc) arm-rtems4.10-binutils-2.20.1-1 |
---|
260 | reporting: tools/rtems-binutils-2.20.1-1.cfg -> |
---|
261 | arm-rtems4.10-binutils-2.20.1-1.html |
---|
262 | config: tools/rtems-gcc-4.4.7-newlib-1.18.0-1.cfg |
---|
263 | package: arm-rtems4.10-gcc-4.4.7-newlib-1.18.0-1 |
---|
264 | building: arm-rtems4.10-gcc-4.4.7-newlib-1.18.0-1 |
---|
265 | package: (Cxc) arm-rtems4.10-gcc-4.4.7-newlib-1.18.0-1 |
---|
266 | building: (Cxc) arm-rtems4.10-gcc-4.4.7-newlib-1.18.0-1 |
---|
267 | reporting: tools/rtems-gcc-4.4.7-newlib-1.18.0-1.cfg -> |
---|
268 | arm-rtems4.10-gcc-4.4.7-newlib-1.18.0-1.html |
---|
269 | config: tools/rtems-gdb-7.3.1-1.cfg |
---|
270 | package: arm-rtems4.10-gdb-7.3.1-1 |
---|
271 | building: arm-rtems4.10-gdb-7.3.1-1 |
---|
272 | reporting: tools/rtems-gdb-7.3.1-1.cfg -> arm-rtems4.10-gdb-7.3.1-1.html |
---|
273 | config: tools/rtems-kernel-4.10.2.cfg |
---|
274 | package: arm-rtems4.10-kernel-4.10.2-1 |
---|
275 | building: arm-rtems4.10-kernel-4.10.2-1 |
---|
276 | reporting: tools/rtems-kernel-4.10.2.cfg -> arm-rtems4.10-kernel-4.10.2-1.html |
---|
277 | installing: expat-2.1.0-x86_64-w64-mingw32-1 -> /cygdrive/c/Users/chris/development/rtems/4.10 |
---|
278 | installing: arm-rtems4.10-binutils-2.20.1-1 -> /cygdrive/c/Users/chris/development/rtems/4.10 <3> |
---|
279 | installing: arm-rtems4.10-gcc-4.4.7-newlib-1.18.0-1 -> /cygdrive/c/Users/chris/development/rtems/4.10 |
---|
280 | installing: arm-rtems4.10-gdb-7.3.1-1 -> /cygdrive/c/Users/chris/development/rtems/4.10 |
---|
281 | installing: arm-rtems4.10-kernel-4.10.2-1 -> /cygdrive/c/Users/chris/development/rtems/4.10 |
---|
282 | cleaning: expat-2.1.0-x86_64-w64-mingw32-1 |
---|
283 | cleaning: arm-rtems4.10-binutils-2.20.1-1 |
---|
284 | cleaning: arm-rtems4.10-gcc-4.4.7-newlib-1.18.0-1 |
---|
285 | cleaning: arm-rtems4.10-gdb-7.3.1-1 |
---|
286 | cleaning: arm-rtems4.10-kernel-4.10.2-1 |
---|
287 | Build Set: Time 10:09:42.810547 <4> |
---|
288 | |
---|
289 | .. topic:: Items: |
---|
290 | |
---|
291 | 1. The Cygwin version of the ARM cross-binutils. |
---|
292 | |
---|
293 | 2. The +(Cxc)+ indicates this is the MinGW build of the package. |
---|
294 | |
---|
295 | 3. Only the MinGW version is installed. |
---|
296 | |
---|
297 | 4. Cygwin is slow so please be patient. This time was on an AMD Athlon 64bit |
---|
298 | Dual Core 6000+ running at 3GHz with 4G RAM running Windows 7 64bit. |
---|
299 | |
---|
300 | .. warning:: |
---|
301 | |
---|
302 | Cygwin documents the 'Big List Of Dodgy Apps' or 'BLODA'. The link is |
---|
303 | http://cygwin.com/faq/faq.html#faq.using.bloda and it is worth a look. You |
---|
304 | will see a large number of common pieces of software found on Windows systems |
---|
305 | that can cause problems. My testing has been performed with NOD32 running and |
---|
306 | I have seen some failures. The list is for all of Cygwin so I am not sure |
---|
307 | which of the listed programs effect the RTEMS Source Biulder. The following |
---|
308 | FAQ item talks about *fork* failures and presents some technical reasons they |
---|
309 | cannot be avoided in all cases. Cygwin and it's fork MSYS are fantastic |
---|
310 | pieces of software in a difficult environment. I have found building a single |
---|
311 | tool tends to work, building all at once is harder. |
---|