source: rtems-docs/user/hosts/windows.rst @ 86518bd

4.115am
Last change on this file since 86518bd was 86518bd, checked in by Chris Johns <chrisj@…>, on 07/04/16 at 02:30:09

Reorganisse the User Manual to make it easier to navigate.

  • Property mode set to 100644
File size: 21.9 KB
Line 
1.. comment SPDX-License-Identifier: CC-BY-SA-4.0
2
3.. comment: Copyright (c) 2016 Chris Johns <chrisj@rtems.org>
4.. comment: All rights reserved.
5
6.. _microsoft-windows:
7
8Microsoft Windows
9~~~~~~~~~~~~~~~~~
10
11RTEMS supports Windows as a development host and the tools for most
12architectures are available. The RTEMS Project relies on the GNU tools for
13compilers and debuggers and we use the simulators that come with GDB and
14QEMU. The Windows support for these tools varies and the RTEMS Project is
15committed to helping the open source community improve the Windows
16experience. If something is not working or supported please email the
17:r:list:`users`.
18
19The RTEMS Project's Windows tools are native Windows executables giving the
20user the best possible experience on Windows. Native Windows programs use the
21standard Windows DLLs and paths. Integration with standard Windows integrated
22development tools such as editors is straight forward. POSIX emulation
23environments such as Cygwin and the MSYS2 shell have special executables that
24require a POSIX emulation DLL and these emulation DLLs add an extra layer of
25complexity as well as a performance over-head. The RTEMS Project uses these
26POSIX emulation shells to run configure scripts that come with various open
27source packages such as `gcc` so they form an important and valued part of the
28environment we describe here. The output of this procedure forms the tools you
29use during your application development and they do not depend on the emulation
30DLLs.
31
32The performance of the compiler is as good as you can have on Windows and the
33performance compiling a single file will be similar to that on a host like
34Linux or FreeBSD given the same hardware. Building the tools from source is
35much slower on Windows because POSIX shells and related tools are used and the
36POSIX emulation overhead it much much slower than a native POSIX operating
37system like Linux and FreeBSD. This overhead is only during the building of the
38tools and the RTEMS kernel and if you use a suitable build system that is
39native to Windows your application development should be similar to other
40operating systems.
41
42Building is known to work on `Windows 7 64bit Professional` and `Windows 10`.
43
44.. _windows-path-length:
45
46Windows Path Length
47^^^^^^^^^^^^^^^^^^^
48
49Windows path length is limited and can cause problems when building the
50tools. The standard Windows API has a ``MAX_PATH`` length of 260
51characters. This can effect some of the tools used by RTEMS. It is recommended
52you keep the top level directories as short as possible when building the RTEMS
53tools and you should also keep an eye on the path length when developing your
54application. The RTEMS built tools can handle much longer path lengths however
55some of the GNU tools such as those in the ``binutils`` package cannot.
56
57The release packages of the RSB when unpacked have top level file names that
58are too big to build RTEMS. You need to change or rename that path to something
59smaller to build. This is indicated in :ref:`released-version`.
60
61.. _msys2_parallel_builds:
62
63Parallel Builds with Make
64^^^^^^^^^^^^^^^^^^^^^^^^^
65
66The MSYS2 GNU ``make`` has problems when using the `jobs` option. The RSB
67defaults to automatically using as many cores as the host machine has. To get a
68successful build on Windows it is recommended you add the ``--jobs=none``
69option to all RSB build set commands.
70
71POSIX Support
72^^^^^^^^^^^^^
73
74Building the RTEMS compilers, debugger, the RTEMS kernel and a number of other
753rd party packages requires a POSIX environment. On Windows you can use Cygwin
76or MSYS2. This document focuses on MSYS2. It is smaller than Cygwin and comes
77with the Arch Linux package manager ``pacman``.
78
79MSYS2 provides MinGW64 support as well as a POSIX shell called MSYS2. The
80MinGW64 compiler and related tools produce 64bit native Windows
81executables. The shell is a standard Bourne shell and the MSYS2 environment is
82a stripped Cygwin shell with enough support to run the various ``configure``
83scripts needed to build the RTEMS tools and the RTEMS kernel.
84
85MSYS2 is built around the ``pacman`` packaging tool. This makes MSYS2 a
86distribution and that is a welcome feature on Windows. You get a powerful tool
87to manage your development environment on Windows.
88
89Python
90^^^^^^
91
92We need Python to build the tools as the RSB is written in Python and we need
93suitable Python libraries to link to GDB as RTEMS makes use of GDB's Python
94support. This places specific demands on the Python we need installed and
95available and MSYS2 provides suitable Python versions we can use. You need to
96make sure you have the correct type and version of Python installed.
97
98We cannot use the Python executables created by the Python project (python.org)
99as they are built by Microsoft's C (MSC) compiler. Linking the MSC Python
100libraries with the MinGW64 executables is not easy and MSYS provides us with a
101simple solution so we do not support linking MSC libraries.
102
103MSYS2 provides two types and two versions of Python executables, MinGW and MSYS
104and Python version 2 and 3. For Windows we need the MinGW executable so we have
105suitables libraries and we have to have Python version 2 because on Windows GDB
106only builds with Python2.
107
108You also need to install the MSYS version of Python along with the MinGW64
109Python2 package. The MSYS Python is version 3 and the RSB can support version 2
110and 3 of Python and it helps handle some of the long paths building GCC can
111generate.
112
113.. _microsoft-windows-installation:
114
115Installing MSYS2
116^^^^^^^^^^^^^^^^
117
118MSYS2 is installed on a new machine using the MSYS2 installer found on
119https://msys2.github.io/. Please select the ``x86_64`` variant for 64bit
120support. Run the installer following the 7 steps listed on the page.
121
122MSYS2 uses the ``pacman`` package manager. The Arch Linux project has detailed
123documentation on how to use ``pacman``. What is shown here is a just few
124examples of what you can do.
125
126.. sidebar:: **Pin MSYS2 Shell to Taskbar**
127
128  Pin the MSYS2 64bit Shell to the Taskbar so you always use it rather than the
129  32bit Shell.
130
131Open a 64bit MSYS shell from the Start Menu:
132
133.. figure:: ../../images/msys2-minw64-start-menu.png
134  :width: 50%
135  :align: center
136  :alt: MSYS2 64bit Shell Start Menu
137
138The packages we require are:
139
140* python
141* mingw-w64-x86_64-python2
142* mingw-w64-x86_64-gcc
143* git
144* bison
145* cvs
146* diffutils
147* make
148* patch
149* tar
150* texinfo
151* unzip
152
153.. note::
154
155  The actual output provided may vary due to changes in the dependent packages
156  or newer package versions.
157
158Install the packages using ``pacman``:
159
160.. code-block:: shell
161
162  ~
163  $ pacman -S python mingw-w64-x86_64-python2 mingw-w64-x86_64-gcc \
164  bison cvs diffutils git make patch tar texinfo unzip
165  resolving dependencies...
166  looking for conflicting packages...
167
168  Packages (74) db-5.3.28-2  expat-2.1.0-2  gdbm-1.11-3  heimdal-1.5.3-8
169                libgdbm-1.11-3  mingw-w64-x86_64-binutils-2.26-21
170                mingw-w64-x86_64-bzip2-1.0.6-5
171                mingw-w64-x86_64-ca-certificates-20150426-2
172                mingw-w64-x86_64-crt-git-5.0.0.4627.03684c4-1
173                mingw-w64-x86_64-expat-2.1.0-6  mingw-w64-x86_64-gcc-libs-5.3.0-2
174                mingw-w64-x86_64-gdbm-1.11-3  mingw-w64-x86_64-gettext-0.19.6-2
175                mingw-w64-x86_64-gmp-6.1.0-1
176                mingw-w64-x86_64-headers-git-5.0.0.4627.53be55d-1
177                mingw-w64-x86_64-isl-0.15-1  mingw-w64-x86_64-libffi-3.2.1-3
178                mingw-w64-x86_64-libiconv-1.14-5
179                mingw-w64-x86_64-libsystre-1.0.1-2
180                mingw-w64-x86_64-libtasn1-4.7-1
181                mingw-w64-x86_64-libtre-git-r122.c2f5d13-4
182                mingw-w64-x86_64-libwinpthread-git-5.0.0.4573.628fdbf-1
183                mingw-w64-x86_64-mpc-1.0.3-2  mingw-w64-x86_64-mpfr-3.1.3.p0-2
184                mingw-w64-x86_64-ncurses-6.0.20160220-2
185                mingw-w64-x86_64-openssl-1.0.2.g-1
186                mingw-w64-x86_64-p11-kit-0.23.1-3
187                mingw-w64-x86_64-readline-6.3.008-1  mingw-w64-x86_64-tcl-8.6.5-1
188                mingw-w64-x86_64-termcap-1.3.1-2  mingw-w64-x86_64-tk-8.6.5-1
189                mingw-w64-x86_64-windows-default-manifest-6.4-2
190                mingw-w64-x86_64-winpthreads-git-5.0.0.4573.628fdbf-1
191                mingw-w64-x86_64-zlib-1.2.8-9  openssh-7.1p2-1  perl-5.22.0-2
192                perl-Authen-SASL-2.16-2  perl-Convert-BinHex-1.123-2
193                perl-Encode-Locale-1.04-1  perl-Error-0.17024-1
194                perl-File-Listing-6.04-2  perl-HTML-Parser-3.71-3
195                perl-HTML-Tagset-3.20-2  perl-HTTP-Cookies-6.01-2
196                perl-HTTP-Daemon-6.01-2  perl-HTTP-Date-6.02-2
197                perl-HTTP-Message-6.06-2  perl-HTTP-Negotiate-6.01-2
198                perl-IO-Socket-SSL-2.016-1  perl-IO-stringy-2.111-1
199                perl-LWP-MediaTypes-6.02-2  perl-MIME-tools-5.506-1
200                perl-MailTools-2.14-1  perl-Net-HTTP-6.09-1
201                perl-Net-SMTP-SSL-1.02-1  perl-Net-SSLeay-1.70-1
202                perl-TermReadKey-2.33-1  perl-TimeDate-2.30-2  perl-URI-1.68-1
203                perl-WWW-RobotRules-6.02-2  perl-libwww-6.13-1  vim-7.4.1468-1
204                bison-3.0.4-1  cvs-1.11.23-2  diffutils-3.3-3  git-2.7.2-1
205                make-4.1-4  mingw-w64-x86_64-gcc-5.3.0-2
206                mingw-w64-x86_64-python2-2.7.11-4  patch-2.7.5-1  python-3.4.3-3
207                tar-1.28-3  texinfo-6.0-1  unzip-6.0-2
208
209  Total Download Size:   114.10 MiB
210  Total Installed Size:  689.61 MiB
211
212  :: Proceed with installation? [Y/n] y
213  :: Retrieving packages...
214   mingw-w64-x86_64-gm...   477.1 KiB   681K/s 00:01 [#####################] 100%
215   mingw-w64-x86_64-li...    24.2 KiB   755K/s 00:00 [#####################] 100%
216   mingw-w64-x86_64-gc...   541.9 KiB   705K/s 00:01 [#####################] 100%
217   mingw-w64-x86_64-ex...   106.7 KiB   702K/s 00:00 [#####################] 100%
218   mingw-w64-x86_64-bz...    77.9 KiB   666K/s 00:00 [#####################] 100%
219   mingw-w64-x86_64-li...   600.2 KiB   703K/s 00:01 [#####################] 100%
220   mingw-w64-x86_64-ge...     3.0 MiB   700K/s 00:04 [#####################] 100%
221   mingw-w64-x86_64-gd...   151.8 KiB   483K/s 00:00 [#####################] 100%
222   mingw-w64-x86_64-li...    34.5 KiB   705K/s 00:00 [#####################] 100%
223   mingw-w64-x86_64-li...    69.2 KiB   713K/s 00:00 [#####################] 100%
224   mingw-w64-x86_64-li...     9.3 KiB   778K/s 00:00 [#####################] 100%
225   mingw-w64-x86_64-nc...  1800.5 KiB   701K/s 00:03 [#####################] 100%
226   mingw-w64-x86_64-li...   171.4 KiB   708K/s 00:00 [#####################] 100%
227   mingw-w64-x86_64-p1...   193.5 KiB   709K/s 00:00 [#####################] 100%
228   mingw-w64-x86_64-ca...   382.1 KiB   705K/s 00:01 [#####################] 100%
229   mingw-w64-x86_64-zl...   148.6 KiB   704K/s 00:00 [#####################] 100%
230   mingw-w64-x86_64-op...     3.3 MiB   624K/s 00:05 [#####################] 100%
231   mingw-w64-x86_64-te...    12.6 KiB  76.7K/s 00:00 [#####################] 100%
232   mingw-w64-x86_64-re...   327.4 KiB   277K/s 00:01 [#####################] 100%
233   mingw-w64-x86_64-tc...     2.9 MiB   699K/s 00:04 [#####################] 100%
234   mingw-w64-x86_64-tk...  1869.2 KiB   703K/s 00:03 [#####################] 100%
235   mingw-w64-x86_64-py...    10.9 MiB   699K/s 00:16 [#####################] 100%
236   mingw-w64-x86_64-bi...    12.7 MiB   688K/s 00:19 [#####################] 100%
237   mingw-w64-x86_64-he...     5.0 MiB   645K/s 00:08 [#####################] 100%
238   mingw-w64-x86_64-cr...     2.6 MiB   701K/s 00:04 [#####################] 100%
239   mingw-w64-x86_64-is...   524.3 KiB   684K/s 00:01 [#####################] 100%
240   mingw-w64-x86_64-mp...   265.2 KiB   705K/s 00:00 [#####################] 100%
241   mingw-w64-x86_64-mp...    62.3 KiB  82.9K/s 00:01 [#####################] 100%
242   mingw-w64-x86_64-wi...  1484.0   B  0.00B/s 00:00 [#####################] 100%
243   mingw-w64-x86_64-wi...    33.2 KiB   346K/s 00:00 [#####################] 100%
244   mingw-w64-x86_64-gc...    25.1 MiB   701K/s 00:37 [#####################] 100%
245   python-3.4.3-3-x86_64     12.1 MiB   700K/s 00:18 [#####################] 100%
246   bison-3.0.4-1-x86_64    1045.1 KiB   703K/s 00:01 [#####################] 100%
247   heimdal-1.5.3-8-x86_64   543.7 KiB   703K/s 00:01 [#####################] 100%
248   cvs-1.11.23-2-x86_64     508.2 KiB   388K/s 00:01 [#####################] 100%
249   diffutils-3.3-3-x86_64   265.7 KiB   478K/s 00:01 [#####################] 100%
250   expat-2.1.0-2-x86_64      13.1 KiB   817K/s 00:00 [#####################] 100%
251   vim-7.4.1468-1-x86_64      6.1 MiB   700K/s 00:09 [#####################] 100%
252   openssh-7.1p2-1-x86_64   653.4 KiB   703K/s 00:01 [#####################] 100%
253   db-5.3.28-2-x86_64        41.7 KiB   719K/s 00:00 [#####################] 100%
254   libgdbm-1.11-3-x86_64     20.4 KiB   754K/s 00:00 [#####################] 100%
255   gdbm-1.11-3-x86_64       108.5 KiB   704K/s 00:00 [#####################] 100%
256   perl-5.22.0-2-x86_64      12.4 MiB   702K/s 00:18 [#####################] 100%
257   perl-Error-0.17024-...    17.1 KiB   742K/s 00:00 [#####################] 100%
258   perl-Authen-SASL-2....    42.4 KiB   731K/s 00:00 [#####################] 100%
259   perl-Encode-Locale-...     9.7 KiB   745K/s 00:00 [#####################] 100%
260   perl-HTTP-Date-6.02...     8.6 KiB   784K/s 00:00 [#####################] 100%
261   perl-File-Listing-6...     7.7 KiB   769K/s 00:00 [#####################] 100%
262   perl-HTML-Tagset-3....    10.3 KiB   732K/s 00:00 [#####################] 100%
263   perl-HTML-Parser-3....    76.9 KiB   516K/s 00:00 [#####################] 100%
264   perl-LWP-MediaTypes...    18.0 KiB   752K/s 00:00 [#####################] 100%
265   perl-URI-1.68-1-any       75.6 KiB   609K/s 00:00 [#####################] 100%
266   perl-HTTP-Message-6...    71.3 KiB   625K/s 00:00 [#####################] 100%
267   perl-HTTP-Cookies-6...    20.4 KiB   499K/s 00:00 [#####################] 100%
268   perl-HTTP-Daemon-6....    14.2 KiB   749K/s 00:00 [#####################] 100%
269   perl-HTTP-Negotiate...    11.4 KiB   817K/s 00:00 [#####################] 100%
270   perl-Net-HTTP-6.09-...    19.8 KiB   732K/s 00:00 [#####################] 100%
271   perl-WWW-RobotRules...    12.2 KiB   766K/s 00:00 [#####################] 100%
272   perl-libwww-6.13-1-any   122.2 KiB   661K/s 00:00 [#####################] 100%
273   perl-TimeDate-2.30-...    35.9 KiB   718K/s 00:00 [#####################] 100%
274   perl-MailTools-2.14...    58.4 KiB   712K/s 00:00 [#####################] 100%
275   perl-IO-stringy-2.1...    52.6 KiB   721K/s 00:00 [#####################] 100%
276   perl-Convert-BinHex...    30.1 KiB   733K/s 00:00 [#####################] 100%
277   perl-MIME-tools-5.5...   180.4 KiB   705K/s 00:00 [#####################] 100%
278   perl-Net-SSLeay-1.7...   191.2 KiB   708K/s 00:00 [#####################] 100%
279   perl-IO-Socket-SSL-...   112.5 KiB   703K/s 00:00 [#####################] 100%
280   perl-Net-SMTP-SSL-1...     3.5 KiB   881K/s 00:00 [#####################] 100%
281   perl-TermReadKey-2....    20.9 KiB   745K/s 00:00 [#####################] 100%
282   git-2.7.2-1-x86_64         3.6 MiB   702K/s 00:05 [#####################] 100%
283   make-4.1-4-x86_64        387.0 KiB   671K/s 00:01 [#####################] 100%
284   patch-2.7.5-1-x86_64      75.9 KiB   684K/s 00:00 [#####################] 100%
285   tar-1.28-3-x86_64        671.9 KiB   379K/s 00:02 [#####################] 100%
286   texinfo-6.0-1-x86_64     992.7 KiB   625K/s 00:02 [#####################] 100%
287   unzip-6.0-2-x86_64        93.1 KiB   705K/s 00:00 [#####################] 100%
288  (74/74) checking keys in keyring                   [#####################] 100%
289  (74/74) checking package integrity                 [#####################] 100%
290  (74/74) loading package files                      [#####################] 100%
291  (74/74) checking for file conflicts                [#####################] 100%
292  (74/74) checking available disk space              [#####################] 100%
293  :: Processing package changes...
294  ( 1/74) installing python                          [#####################] 100%
295  ( 2/74) installing mingw-w64-x86_64-gmp            [#####################] 100%
296  ( 3/74) installing mingw-w64-x86_64-libwinpthr...  [#####################] 100%
297  ( 4/74) installing mingw-w64-x86_64-gcc-libs       [#####################] 100%
298  ( 5/74) installing mingw-w64-x86_64-expat          [#####################] 100%
299  ( 6/74) installing mingw-w64-x86_64-bzip2          [#####################] 100%
300  ( 7/74) installing mingw-w64-x86_64-libiconv       [#####################] 100%
301  ( 8/74) installing mingw-w64-x86_64-gettext        [#####################] 100%
302  ( 9/74) installing mingw-w64-x86_64-gdbm           [#####################] 100%
303  (10/74) installing mingw-w64-x86_64-libffi         [#####################] 100%
304  (11/74) installing mingw-w64-x86_64-libtre-git     [#####################] 100%
305  (12/74) installing mingw-w64-x86_64-libsystre      [#####################] 100%
306  (13/74) installing mingw-w64-x86_64-ncurses        [#####################] 100%
307  (14/74) installing mingw-w64-x86_64-libtasn1       [#####################] 100%
308  (15/74) installing mingw-w64-x86_64-p11-kit        [#####################] 100%
309  (16/74) installing mingw-w64-x86_64-ca-certifi...  [#####################] 100%
310  (17/74) installing mingw-w64-x86_64-zlib           [#####################] 100%
311  (18/74) installing mingw-w64-x86_64-openssl        [#####################] 100%
312  (19/74) installing mingw-w64-x86_64-termcap        [#####################] 100%
313  (20/74) installing mingw-w64-x86_64-readline       [#####################] 100%
314  (21/74) installing mingw-w64-x86_64-tcl            [#####################] 100%
315  (22/74) installing mingw-w64-x86_64-tk             [#####################] 100%
316  (23/74) installing mingw-w64-x86_64-python2        [#####################] 100%
317  (24/74) installing mingw-w64-x86_64-binutils       [#####################] 100%
318  (25/74) installing mingw-w64-x86_64-headers-git    [#####################] 100%
319  (26/74) installing mingw-w64-x86_64-crt-git        [#####################] 100%
320  (27/74) installing mingw-w64-x86_64-isl            [#####################] 100%
321  (28/74) installing mingw-w64-x86_64-mpfr           [#####################] 100%
322  (29/74) installing mingw-w64-x86_64-mpc            [#####################] 100%
323  (30/74) installing mingw-w64-x86_64-windows-de...  [#####################] 100%
324  (31/74) installing mingw-w64-x86_64-winpthread...  [#####################] 100%
325  (32/74) installing mingw-w64-x86_64-gcc            [#####################] 100%
326  (33/74) installing bison                           [#####################] 100%
327  (34/74) installing heimdal                         [#####################] 100%
328  (35/74) installing cvs                             [#####################] 100%
329  (36/74) installing diffutils                       [#####################] 100%
330  (37/74) installing expat                           [#####################] 100%
331  (38/74) installing vim                             [#####################] 100%
332  (39/74) installing openssh                         [#####################] 100%
333  (40/74) installing db                              [#####################] 100%
334  (41/74) installing libgdbm                         [#####################] 100%
335  (42/74) installing gdbm                            [#####################] 100%
336  (43/74) installing perl                            [#####################] 100%
337  (44/74) installing perl-Error                      [#####################] 100%
338  (45/74) installing perl-Authen-SASL                [#####################] 100%
339  (46/74) installing perl-Encode-Locale              [#####################] 100%
340  (47/74) installing perl-HTTP-Date                  [#####################] 100%
341  (48/74) installing perl-File-Listing               [#####################] 100%
342  (49/74) installing perl-HTML-Tagset                [#####################] 100%
343  (50/74) installing perl-HTML-Parser                [#####################] 100%
344  (51/74) installing perl-LWP-MediaTypes             [#####################] 100%
345  (52/74) installing perl-URI                        [#####################] 100%
346  (53/74) installing perl-HTTP-Message               [#####################] 100%
347  (54/74) installing perl-HTTP-Cookies               [#####################] 100%
348  (55/74) installing perl-HTTP-Daemon                [#####################] 100%
349  (56/74) installing perl-HTTP-Negotiate             [#####################] 100%
350  (57/74) installing perl-Net-HTTP                   [#####################] 100%
351  (58/74) installing perl-WWW-RobotRules             [#####################] 100%
352  (59/74) installing perl-libwww                     [#####################] 100%
353  Optional dependencies for perl-libwww
354      perl-LWP-Protocol-HTTPS: for https:// url schemes
355  (60/74) installing perl-TimeDate                   [#####################] 100%
356  (61/74) installing perl-MailTools                  [#####################] 100%
357  (62/74) installing perl-IO-stringy                 [#####################] 100%
358  (63/74) installing perl-Convert-BinHex             [#####################] 100%
359  module test... pass.
360  (64/74) installing perl-MIME-tools                 [#####################] 100%
361  (65/74) installing perl-Net-SSLeay                 [#####################] 100%
362  (66/74) installing perl-IO-Socket-SSL              [#####################] 100%
363  (67/74) installing perl-Net-SMTP-SSL               [#####################] 100%
364  (68/74) installing perl-TermReadKey                [#####################] 100%
365  (69/74) installing git                             [#####################] 100%
366  Optional dependencies for git
367      python2: various helper scripts
368      subversion: git svn
369  (70/74) installing make                            [#####################] 100%
370  (71/74) installing patch                           [#####################] 100%
371  Optional dependencies for patch
372      ed: for patch -e functionality
373  (72/74) installing tar                             [#####################] 100%
374  (73/74) installing texinfo                         [#####################] 100%
375  (74/74) installing unzip                           [#####################] 100%
Note: See TracBrowser for help on using the repository browser.