Debian Codegraph @

gcc/ada/doc/gnat_ugn/platform_specific_information.rst

raw
1 .. role:: switch(samp)
2
3 .. -- Non-breaking space in running text
4 -- E.g. Ada |nbsp| 95
5
6 .. |nbsp| unicode:: 0xA0
7 :trim:
8
9 .. _Platform_Specific_Information:
10
11 *****************************
12 Platform-Specific Information
13 *****************************
14
15 This appendix contains information relating to the implementation
16 of run-time libraries on various platforms and also covers topics
17 related to the GNAT implementation on specific Operating Systems.
18
19 .. _`Run_Time_Libraries`:
20
21 Run-Time Libraries
22 ==================
23
24 .. index:: Tasking and threads libraries
25 .. index:: Threads libraries and tasking
26 .. index:: Run-time libraries (platform-specific information)
27
28 The GNAT run-time implementation may vary with respect to both the
29 underlying threads library and the exception-handling scheme.
30 For threads support, the default run-time will bind to the thread
31 package of the underlying operating system.
32
33 For exception handling, either or both of two models are supplied:
34
35 .. index:: Zero-Cost Exceptions
36 .. index:: ZCX (Zero-Cost Exceptions)
37
38 * **Zero-Cost Exceptions** ("ZCX"),
39 which uses binder-generated tables that
40 are interrogated at run time to locate a handler.
41
42 .. index:: setjmp/longjmp Exception Model
43 .. index:: SJLJ (setjmp/longjmp Exception Model)
44
45 * **setjmp / longjmp** ('SJLJ'),
46 which uses dynamically-set data to establish
47 the set of handlers
48
49 Most programs should experience a substantial speed improvement by
50 being compiled with a ZCX run-time.
51 This is especially true for
52 tasking applications or applications with many exception handlers.
53 Note however that the ZCX run-time does not support asynchronous abort
54 of tasks (``abort`` and ``select-then-abort`` constructs) and will instead
55 implement abort by polling points in the runtime. You can also add additional
56 polling points explicitly if needed in your application via ``pragma
57 Abort_Defer``.
58
59 This section summarizes which combinations of threads and exception support
60 are supplied on various GNAT platforms.
61
62 .. _Summary_of_Run-Time_Configurations:
63
64 Summary of Run-Time Configurations
65 ----------------------------------
66
67 +-----------------+--------------+-------------------------+------------+
68 | Platform | Run-Time | Tasking | Exceptions |
69 +=================+==============+=========================+============+
70 | GNU/Linux | rts-native | pthread library | ZCX |
71 | | (default) | | |
72 | +--------------+-------------------------+------------+
73 | | rts-sjlj | pthread library | SJLJ |
74 +-----------------+--------------+-------------------------+------------+
75 | Windows | rts-native | native Win32 threads | ZCX |
76 | | (default) | | |
77 | +--------------+-------------------------+------------+
78 | | rts-sjlj | native Win32 threads | SJLJ |
79 +-----------------+--------------+-------------------------+------------+
80 | Mac OS | rts-native | pthread library | ZCX |
81 +-----------------+--------------+-------------------------+------------+
82
83
84 .. _Specifying_a_Run-Time_Library:
85
86 Specifying a Run-Time Library
87 =============================
88
89 The :file:`adainclude` subdirectory containing the sources of the GNAT
90 run-time library, and the :file:`adalib` subdirectory containing the
91 :file:`ALI` files and the static and/or shared GNAT library, are located
92 in the gcc target-dependent area:
93
94
95 ::
96
97 target=$prefix/lib/gcc/gcc-*dumpmachine*/gcc-*dumpversion*/
98
99 As indicated above, on some platforms several run-time libraries are supplied.
100 These libraries are installed in the target dependent area and
101 contain a complete source and binary subdirectory. The detailed description
102 below explains the differences between the different libraries in terms of
103 their thread support.
104
105 The default run-time library (when GNAT is installed) is *rts-native*.
106 This default run-time is selected by the means of soft links.
107 For example on x86-linux:
108
109 .. --
110 -- $(target-dir)
111 -- |
112 -- +--- adainclude----------+
113 -- | |
114 -- +--- adalib-----------+ |
115 -- | | |
116 -- +--- rts-native | |
117 -- | | | |
118 -- | +--- adainclude <---+
119 -- | | |
120 -- | +--- adalib <----+
121 -- |
122 -- +--- rts-sjlj
123 -- |
124 -- +--- adainclude
125 -- |
126 -- +--- adalib
127
128 .. only:: html or latex
129
130 .. image:: rtlibrary-structure.png
131
132 .. only:: not (html or latex)
133
134 ::
135
136 $(target-dir)
137 __/ / \ \___
138 _______/ / \ \_________________
139 / / \ \
140 / / \ \
141 ADAINCLUDE ADALIB rts-native rts-sjlj
142 : : / \ / \
143 : : / \ / \
144 : : / \ / \
145 : : / \ / \
146 +-------------> adainclude adalib adainclude adalib
147 : ^
148 : :
149 +---------------------+
150
151 Run-Time Library Directory Structure
152 (Upper-case names and dotted/dashed arrows represent soft links)
153
154 If the *rts-sjlj* library is to be selected on a permanent basis,
155 these soft links can be modified with the following commands:
156
157 ::
158
159 $ cd $target
160 $ rm -f adainclude adalib
161 $ ln -s rts-sjlj/adainclude adainclude
162 $ ln -s rts-sjlj/adalib adalib
163
164 Alternatively, you can specify :file:`rts-sjlj/adainclude` in the file
165 :file:`$target/ada_source_path` and :file:`rts-sjlj/adalib` in
166 :file:`$target/ada_object_path`.
167
168 .. index:: --RTS option
169
170 Selecting another run-time library temporarily can be
171 achieved by using the :switch:`--RTS` switch, e.g., :switch:`--RTS=sjlj`
172
173
174 .. _Choosing_the_Scheduling_Policy:
175
176 .. index:: SCHED_FIFO scheduling policy
177 .. index:: SCHED_RR scheduling policy
178 .. index:: SCHED_OTHER scheduling policy
179
180 Choosing the Scheduling Policy
181 ------------------------------
182
183 When using a POSIX threads implementation, you have a choice of several
184 scheduling policies: ``SCHED_FIFO``, ``SCHED_RR`` and ``SCHED_OTHER``.
185
186 Typically, the default is ``SCHED_OTHER``, while using ``SCHED_FIFO``
187 or ``SCHED_RR`` requires special (e.g., root) privileges.
188
189 .. index:: pragma Time_Slice
190 .. index:: -T0 option
191 .. index:: pragma Task_Dispatching_Policy
192
193
194 By default, GNAT uses the ``SCHED_OTHER`` policy. To specify
195 ``SCHED_FIFO``,
196 you can use one of the following:
197
198 * ``pragma Time_Slice (0.0)``
199 * the corresponding binder option :switch:`-T0`
200 * ``pragma Task_Dispatching_Policy (FIFO_Within_Priorities)``
201
202
203 To specify ``SCHED_RR``,
204 you should use ``pragma Time_Slice`` with a
205 value greater than 0.0, or else use the corresponding :switch:`-T`
206 binder option.
207
208
209 To make sure a program is running as root, you can put something like
210 this in a library package body in your application:
211
212 .. code-block:: ada
213
214 function geteuid return Integer;
215 pragma Import (C, geteuid, "geteuid");
216 Ignore : constant Boolean :=
217 (if geteuid = 0 then True else raise Program_Error with "must be root");
218
219 It gets the effective user id, and if it's not 0 (i.e. root), it raises
220 Program_Error. Note that if you re running the code in a container, this may
221 not be sufficient, as you may have sufficient priviledge on the container,
222 but not on the host machine running the container, so check that you also
223 have sufficient priviledge for running the container image.
224
225 .. index:: Linux
226 .. index:: GNU/Linux
227
228 .. _GNU_Linux_Topics:
229
230 GNU/Linux Topics
231 ================
232
233 This section describes topics that are specific to GNU/Linux platforms.
234
235 .. _Required_packages_on_GNU_Linux:
236
237 Required Packages on GNU/Linux
238 ------------------------------
239
240 GNAT requires the C library developer's package to be installed.
241 The name of of that package depends on your GNU/Linux distribution:
242
243 * RedHat, SUSE: ``glibc-devel``;
244 * Debian, Ubuntu: ``libc6-dev`` (normally installed by default).
245
246 If using the 32-bit version of GNAT on a 64-bit version of GNU/Linux,
247 you'll need the 32-bit version of the following packages:
248
249 * RedHat, SUSE: ``glibc.i686``, ``glibc-devel.i686``, ``ncurses-libs.i686``
250 * SUSE: ``glibc-locale-base-32bit``
251 * Debian, Ubuntu: ``libc6:i386``, ``libc6-dev:i386``, ``lib32ncursesw5``
252
253 Other GNU/Linux distributions might be choosing a different name
254 for those packages.
255
256
257 .. _A_GNU_Linux_debug_quirk:
258
259 A GNU/Linux Debug Quirk
260 -----------------------
261
262 On SuSE 15, some kernels have a defect causing issues when debugging
263 programs using threads or Ada tasks. Due to the lack of documentation
264 found regarding this kernel issue, we can only provide limited
265 information about which kernels are impacted: kernel version 5.3.18 is
266 known to be impacted, and kernels in the 5.14 range or newer are
267 believed to fix this problem.
268
269 The bug affects the debugging of 32-bit processes on a 64-bit system.
270 Symptoms can vary: Unexpected ``SIGABRT`` signals being received by
271 the program, "The futex facility returned an unexpected error code"
272 error message, and inferior programs hanging indefinitely range among
273 the symptoms most commonly observed.
274
275 .. index:: Windows
276
277 .. _Microsoft_Windows_Topics:
278
279 Microsoft Windows Topics
280 ========================
281
282 This section describes topics that are specific to the Microsoft Windows
283 platforms.
284
285
286 .. only:: PRO
287
288 .. rubric:: Installing from the Command Line
289
290 By default the GNAT installers display a GUI that prompts you to enter
291 the installation path and similar information, and then guides you through the
292 installation process. It is also possible to perform silent installations
293 using the command-line interface.
294
295 In order to install one of the GNAT installers from the command
296 line you should pass parameter :switch:`/S` (and, optionally,
297 :switch:`/D=<directory>`) as command-line arguments.
298
299 For example, for an unattended installation of
300 GNAT 19.2 into the default directory :file:`C:\\GNATPRO\\19.2` you
301 would run::
302
303 gnatpro-19.2-x86-windows-bin /S
304
305 To install into a custom directory, say, :file:`C:\\TOOLS\\GNATPRO\\19.2`::
306
307 gnatpro-19.2-x86-windows-bin /S /D=C:\TOOLS\GNATPRO\19.2
308
309 You can use the same syntax for all installers.
310
311 Note that unattended installations don't modify system path, nor create file
312 associations, so such activities need to be done by hand.
313
314
315 .. _Using_GNAT_on_Windows:
316
317 Using GNAT on Windows
318 ---------------------
319
320 One of the strengths of the GNAT technology is that its tool set
321 (``gcc``, ``gnatbind``, ``gnatlink``, ``gnatmake``, the
322 ``gdb`` debugger, etc.) is used in the same way regardless of the
323 platform.
324
325 On Windows this tool set is complemented by a number of Microsoft-specific
326 tools that have been provided to facilitate interoperability with Windows
327 when this is required. With these tools:
328
329
330 * You can build applications using the ``CONSOLE`` or ``WINDOWS``
331 subsystems.
332
333 * You can use any Dynamically Linked Library (DLL) in your Ada code (both
334 relocatable and non-relocatable DLLs are supported).
335
336 * You can build Ada DLLs for use in other applications. These applications
337 can be written in a language other than Ada (e.g., C, C++, etc). Again both
338 relocatable and non-relocatable Ada DLLs are supported.
339
340 * You can include Windows resources in your Ada application.
341
342 * You can use or create COM/DCOM objects.
343
344 Immediately below are listed all known general GNAT-for-Windows restrictions.
345 Other restrictions about specific features like Windows Resources and DLLs
346 are listed in separate sections below.
347
348
349 * It is not possible to use ``GetLastError`` and ``SetLastError``
350 when tasking, protected records, or exceptions are used. In these
351 cases, in order to implement Ada semantics, the GNAT run-time system
352 calls certain Win32 routines that set the last error variable to 0 upon
353 success. It should be possible to use ``GetLastError`` and
354 ``SetLastError`` when tasking, protected record, and exception
355 features are not used, but it is not guaranteed to work.
356
357 * It is not possible to link against Microsoft C++ libraries except for
358 import libraries. Interfacing must be done by the mean of DLLs.
359
360 * It is possible to link against Microsoft C libraries. Yet the preferred
361 solution is to use C/C++ compiler that comes with GNAT, since it
362 doesn't require having two different development environments and makes the
363 inter-language debugging experience smoother.
364
365 * When the compilation environment is located on FAT32 drives, users may
366 experience recompilations of the source files that have not changed if
367 Daylight Saving Time (DST) state has changed since the last time files
368 were compiled. NTFS drives do not have this problem.
369
370 * No components of the GNAT toolset use any entries in the Windows
371 registry. The only entries that can be created are file associations and
372 PATH settings, provided the user has chosen to create them at installation
373 time, as well as some minimal book-keeping information needed to correctly
374 uninstall or integrate different GNAT products.
375
376
377 .. _Using_a_network_installation_of_GNAT:
378
379 Using a network installation of GNAT
380 ------------------------------------
381
382 Make sure the system on which GNAT is installed is accessible from the
383 current machine, i.e., the install location is shared over the network.
384 Shared resources are accessed on Windows by means of UNC paths, which
385 have the format ``\\\\server\\sharename\\path``
386
387 In order to use such a network installation, simply add the UNC path of the
388 :file:`bin` directory of your GNAT installation in front of your PATH. For
389 example, if GNAT is installed in :file:`\\GNAT` directory of a share location
390 called :file:`c-drive` on a machine :file:`LOKI`, the following command will
391 make it available:
392
393 ::
394
395 $ path \\loki\c-drive\gnat\bin;%path%`
396
397 Be aware that every compilation using the network installation results in the
398 transfer of large amounts of data across the network and will likely cause
399 serious performance penalty.
400
401 .. _CONSOLE_and_WINDOWS_subsystems:
402
403 CONSOLE and WINDOWS subsystems
404 ------------------------------
405
406 .. index:: CONSOLE Subsystem
407 .. index:: WINDOWS Subsystem
408 .. index:: -mwindows
409
410 There are two main subsystems under Windows. The ``CONSOLE`` subsystem
411 (which is the default subsystem) will always create a console when
412 launching the application. This is not something desirable when the
413 application has a Windows GUI. To get rid of this console the
414 application must be using the ``WINDOWS`` subsystem. To do so
415 the :switch:`-mwindows` linker option must be specified.
416
417 ::
418
419 $ gnatmake winprog -largs -mwindows
420
421 .. _Temporary_Files:
422
423 Temporary Files
424 ---------------
425
426 .. index:: Temporary files
427
428 It is possible to control where temporary files gets created by setting
429 the :envvar:`TMP` environment variable. The file will be created:
430
431 * Under the directory pointed to by the :envvar:`TMP` environment variable if
432 this directory exists.
433
434 * Under :file:`c:\\temp`, if the :envvar:`TMP` environment variable is not
435 set (or not pointing to a directory) and if this directory exists.
436
437 * Under the current working directory otherwise.
438
439 This allows you to determine exactly where the temporary
440 file will be created. This is particularly useful in networked
441 environments where you may not have write access to some
442 directories.
443
444 Disabling Command Line Argument Expansion
445 -----------------------------------------
446
447 .. index:: Command Line Argument Expansion
448
449 By default, an executable compiled for the Windows platform will do
450 the following postprocessing on the arguments passed on the command
451 line:
452
453 * If the argument contains the characters ``*`` and/or ``?``, then
454 file expansion will be attempted. For example, if the current directory
455 contains :file:`a.txt` and :file:`b.txt`, then when calling::
456
457 $ my_ada_program *.txt
458
459 The following arguments will effectively be passed to the main program
460 (for example when using ``Ada.Command_Line.Argument``)::
461
462 Ada.Command_Line.Argument (1) -> "a.txt"
463 Ada.Command_Line.Argument (2) -> "b.txt"
464
465 * Filename expansion can be disabled for a given argument by using single
466 quotes. Thus, calling::
467
468 $ my_ada_program '*.txt'
469
470 will result in::
471
472 Ada.Command_Line.Argument (1) -> "*.txt"
473
474 Note that if the program is launched from a shell such as Cygwin Bash
475 then quote removal might be performed by the shell.
476
477 In some contexts it might be useful to disable this feature (for example if
478 the program performs its own argument expansion). In order to do this, a C
479 symbol needs to be defined and set to ``0``. You can do this by
480 adding the following code fragment in one of your Ada units:
481
482 .. code-block:: ada
483
484 Do_Argv_Expansion : Integer := 0;
485 pragma Export (C, Do_Argv_Expansion, "__gnat_do_argv_expansion");
486
487 The results of previous examples will be respectively::
488
489 Ada.Command_Line.Argument (1) -> "*.txt"
490
491 and::
492
493 Ada.Command_Line.Argument (1) -> "'*.txt'"
494
495
496 Windows Socket Timeouts
497 -----------------------
498
499 Microsoft Windows desktops older than ``8.0`` and Microsoft Windows Servers
500 older than ``2019`` set a socket timeout 500 milliseconds longer than the value
501 set by setsockopt with ``SO_RCVTIMEO`` and ``SO_SNDTIMEO`` options. The GNAT
502 runtime makes a correction for the difference in the corresponding Windows
503 versions. For Windows Server starting with version ``2019``, the user must
504 provide a manifest file for the GNAT runtime to be able to recognize that
505 the Windows version does not need the timeout correction. The manifest file
506 should be located in the same directory as the executable file, and its file
507 name must match the executable name suffixed by ``.manifest``. For example,
508 if the executable name is :file:`sock_wto.exe`, then the manifest file name
509 has to be :file:`sock_wto.exe.manifest`. The manifest file must contain at
510 least the following data::
511
512 <?xml version="1.0" encoding="UTF-8" standalone="yes"?>
513 <assembly xmlns="urn:schemas-microsoft-com:asm.v1" manifestVersion="1.0">
514 <compatibility xmlns="urn:schemas-microsoft-com:compatibility.v1">
515 <application>
516 <!-- Windows Vista -->
517 <supportedOS Id="{e2011457-1546-43c5-a5fe-008deee3d3f0}"/>
518 <!-- Windows 7 -->
519 <supportedOS Id="{35138b9a-5d96-4fbd-8e2d-a2440225f93a}"/>
520 <!-- Windows 8 -->
521 <supportedOS Id="{4a2f28e3-53b9-4441-ba9c-d69d4a4a6e38}"/>
522 <!-- Windows 8.1 -->
523 <supportedOS Id="{1f676c76-80e1-4239-95bb-83d0f6d0da78}"/>
524 <!-- Windows 10 -->
525 <supportedOS Id="{8e0f7a12-bfb3-4fe8-b9a5-48fd50a15a9a}"/>
526 </application>
527 </compatibility>
528 </assembly>
529
530 Without the manifest file, the socket timeout is going to be overcorrected on
531 these Windows Server versions and the actual time is going to be 500
532 milliseconds shorter than what was set with GNAT.Sockets.Set_Socket_Option.
533 Note that on Microsoft Windows versions where correction is necessary, there
534 is no way to set a socket timeout shorter than 500 ms. If a socket timeout
535 shorter than 500 ms is needed on these Windows versions, a call to
536 Check_Selector should be added before any socket read or write operations.
537
538
539 .. _Mixed-Language_Programming_on_Windows:
540
541 Mixed-Language Programming on Windows
542 -------------------------------------
543
544 Developing pure Ada applications on Windows is no different than on
545 other GNAT-supported platforms. However, when developing or porting an
546 application that contains a mix of Ada and C/C++, the choice of your
547 Windows C/C++ development environment conditions your overall
548 interoperability strategy.
549
550 If you use ``gcc`` or Microsoft C to compile the non-Ada part of
551 your application, there are no Windows-specific restrictions that
552 affect the overall interoperability with your Ada code. If you do want
553 to use the Microsoft tools for your C++ code, you have two choices:
554
555 * Encapsulate your C++ code in a DLL to be linked with your Ada
556 application. In this case, use the Microsoft or whatever environment to
557 build the DLL and use GNAT to build your executable
558 (:ref:`Using_DLLs_with_GNAT`).
559
560 * Or you can encapsulate your Ada code in a DLL to be linked with the
561 other part of your application. In this case, use GNAT to build the DLL
562 (:ref:`Building_DLLs_with_GNAT_Project_files`) and use the Microsoft
563 or whatever environment to build your executable.
564
565 In addition to the description about C main in
566 :ref:`Mixed_Language_Programming` section, if the C main uses a
567 stand-alone library it is required on x86-windows to
568 setup the SEH context. For this the C main must looks like this:
569
570
571 .. code-block:: c
572
573 /* main.c */
574 extern void adainit (void);
575 extern void adafinal (void);
576 extern void __gnat_initialize(void*);
577 extern void call_to_ada (void);
578
579 int main (int argc, char *argv[])
580 {
581 int SEH [2];
582
583 /* Initialize the SEH context */
584 __gnat_initialize (&SEH);
585
586 adainit();
587
588 /* Then call Ada services in the stand-alone library */
589
590 call_to_ada();
591
592 adafinal();
593 }
594
595 Note that this is not needed on x86_64-windows where the Windows
596 native SEH support is used.
597
598
599 .. _Windows_Calling_Conventions:
600
601 Windows Calling Conventions
602 ^^^^^^^^^^^^^^^^^^^^^^^^^^^
603
604 .. index:: Stdcall
605 .. index:: APIENTRY
606
607 This section pertain only to Win32. On Win64 there is a single native
608 calling convention. All convention specifiers are ignored on this
609 platform.
610
611 When a subprogram ``F`` (caller) calls a subprogram ``G``
612 (callee), there are several ways to push ``G``\ 's parameters on the
613 stack and there are several possible scenarios to clean up the stack
614 upon ``G``\ 's return. A calling convention is an agreed upon software
615 protocol whereby the responsibilities between the caller (``F``) and
616 the callee (``G``) are clearly defined. Several calling conventions
617 are available for Windows:
618
619 * ``C`` (Microsoft defined)
620
621 * ``Stdcall`` (Microsoft defined)
622
623 * ``Win32`` (GNAT specific)
624
625 * ``DLL`` (GNAT specific)
626
627
628 .. _C_Calling_Convention:
629
630 ``C`` Calling Convention
631 """"""""""""""""""""""""
632
633 This is the default calling convention used when interfacing to C/C++
634 routines compiled with either ``gcc`` or Microsoft Visual C++.
635
636 In the ``C`` calling convention subprogram parameters are pushed on the
637 stack by the caller from right to left. The caller itself is in charge of
638 cleaning up the stack after the call. In addition, the name of a routine
639 with ``C`` calling convention is mangled by adding a leading underscore.
640
641 The name to use on the Ada side when importing (or exporting) a routine
642 with ``C`` calling convention is the name of the routine. For
643 instance the C function:
644
645 ::
646
647 int get_val (long);
648
649 should be imported from Ada as follows:
650
651 .. code-block:: ada
652
653 function Get_Val (V : Interfaces.C.long) return Interfaces.C.int;
654 pragma Import (C, Get_Val, External_Name => "get_val");
655
656 Note that in this particular case the ``External_Name`` parameter could
657 have been omitted since, when missing, this parameter is taken to be the
658 name of the Ada entity in lower case. When the ``Link_Name`` parameter
659 is missing, as in the above example, this parameter is set to be the
660 ``External_Name`` with a leading underscore.
661
662 When importing a variable defined in C, you should always use the ``C``
663 calling convention unless the object containing the variable is part of a
664 DLL (in which case you should use the ``Stdcall`` calling
665 convention, :ref:`Stdcall_Calling_Convention`).
666
667
668 .. _Stdcall_Calling_Convention:
669
670 ``Stdcall`` Calling Convention
671 """"""""""""""""""""""""""""""
672
673 This convention, which was the calling convention used for Pascal
674 programs, is used by Microsoft for all the routines in the Win32 API for
675 efficiency reasons. It must be used to import any routine for which this
676 convention was specified.
677
678 In the ``Stdcall`` calling convention subprogram parameters are pushed
679 on the stack by the caller from right to left. The callee (and not the
680 caller) is in charge of cleaning the stack on routine exit. In addition,
681 the name of a routine with ``Stdcall`` calling convention is mangled by
682 adding a leading underscore (as for the ``C`` calling convention) and a
683 trailing :samp:`@{nn}`, where ``nn`` is the overall size (in
684 bytes) of the parameters passed to the routine.
685
686 The name to use on the Ada side when importing a C routine with a
687 ``Stdcall`` calling convention is the name of the C routine. The leading
688 underscore and trailing :samp:`@{nn}` are added automatically by
689 the compiler. For instance the Win32 function:
690
691 ::
692
693 APIENTRY int get_val (long);
694
695 should be imported from Ada as follows:
696
697 .. code-block:: ada
698
699 function Get_Val (V : Interfaces.C.long) return Interfaces.C.int;
700 pragma Import (Stdcall, Get_Val);
701 -- On the x86 a long is 4 bytes, so the Link_Name is "_get_val@4"
702
703 As for the ``C`` calling convention, when the ``External_Name``
704 parameter is missing, it is taken to be the name of the Ada entity in lower
705 case. If instead of writing the above import pragma you write:
706
707 .. code-block:: ada
708
709 function Get_Val (V : Interfaces.C.long) return Interfaces.C.int;
710 pragma Import (Stdcall, Get_Val, External_Name => "retrieve_val");
711
712 then the imported routine is ``_retrieve_val@4``. However, if instead
713 of specifying the ``External_Name`` parameter you specify the
714 ``Link_Name`` as in the following example:
715
716 .. code-block:: ada
717
718 function Get_Val (V : Interfaces.C.long) return Interfaces.C.int;
719 pragma Import (Stdcall, Get_Val, Link_Name => "retrieve_val");
720
721 then the imported routine is ``retrieve_val``, that is, there is no
722 decoration at all. No leading underscore and no Stdcall suffix
723 :samp:`@{nn}`.
724
725 This is especially important as in some special cases a DLL's entry
726 point name lacks a trailing :samp:`@{nn}` while the exported
727 name generated for a call has it.
728
729 It is also possible to import variables defined in a DLL by using an
730 import pragma for a variable. As an example, if a DLL contains a
731 variable defined as:
732
733 .. code-block:: c
734
735 int my_var;
736
737 then, to access this variable from Ada you should write:
738
739 .. code-block:: ada
740
741 My_Var : Interfaces.C.int;
742 pragma Import (Stdcall, My_Var);
743
744 Note that to ease building cross-platform bindings this convention
745 will be handled as a ``C`` calling convention on non-Windows platforms.
746
747
748 .. _Win32_Calling_Convention:
749
750 ``Win32`` Calling Convention
751 """"""""""""""""""""""""""""
752
753 This convention, which is GNAT-specific is fully equivalent to the
754 ``Stdcall`` calling convention described above.
755
756
757 .. _DLL_Calling_Convention:
758
759 ``DLL`` Calling Convention
760 """"""""""""""""""""""""""
761
762 This convention, which is GNAT-specific is fully equivalent to the
763 ``Stdcall`` calling convention described above.
764
765
766 .. _Introduction_to_Dynamic_Link_Libraries_DLLs:
767
768 Introduction to Dynamic Link Libraries (DLLs)
769 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
770
771 .. index:: DLL
772
773 A Dynamically Linked Library (DLL) is a library that can be shared by
774 several applications running under Windows. A DLL can contain any number of
775 routines and variables.
776
777 One advantage of DLLs is that you can change and enhance them without
778 forcing all the applications that depend on them to be relinked or
779 recompiled. However, you should be aware than all calls to DLL routines are
780 slower since, as you will understand below, such calls are indirect.
781
782 To illustrate the remainder of this section, suppose that an application
783 wants to use the services of a DLL :file:`API.dll`. To use the services
784 provided by :file:`API.dll` you must statically link against the DLL or
785 an import library which contains a jump table with an entry for each
786 routine and variable exported by the DLL. In the Microsoft world this
787 import library is called :file:`API.lib`. When using GNAT this import
788 library is called either :file:`libAPI.dll.a`, :file:`libapi.dll.a`,
789 :file:`libAPI.a` or :file:`libapi.a` (names are case insensitive).
790
791 After you have linked your application with the DLL or the import library
792 and you run your application, here is what happens:
793
794 * Your application is loaded into memory.
795
796 * The DLL :file:`API.dll` is mapped into the address space of your
797 application. This means that:
798
799 - The DLL will use the stack of the calling thread.
800
801 - The DLL will use the virtual address space of the calling process.
802
803 - The DLL will allocate memory from the virtual address space of the calling
804 process.
805
806 - Handles (pointers) can be safely exchanged between routines in the DLL
807 routines and routines in the application using the DLL.
808
809 * The entries in the jump table (from the import library :file:`libAPI.dll.a`
810 or :file:`API.lib` or automatically created when linking against a DLL)
811 which is part of your application are initialized with the addresses
812 of the routines and variables in :file:`API.dll`.
813
814 * If present in :file:`API.dll`, routines ``DllMain`` or
815 ``DllMainCRTStartup`` are invoked. These routines typically contain
816 the initialization code needed for the well-being of the routines and
817 variables exported by the DLL.
818
819 There is an additional point which is worth mentioning. In the Windows
820 world there are two kind of DLLs: relocatable and non-relocatable
821 DLLs. Non-relocatable DLLs can only be loaded at a very specific address
822 in the target application address space. If the addresses of two
823 non-relocatable DLLs overlap and these happen to be used by the same
824 application, a conflict will occur and the application will run
825 incorrectly. Hence, when possible, it is always preferable to use and
826 build relocatable DLLs. Both relocatable and non-relocatable DLLs are
827 supported by GNAT. Note that the :switch:`-s` linker option (see GNU Linker
828 User's Guide) removes the debugging symbols from the DLL but the DLL can
829 still be relocated.
830
831 As a side note, an interesting difference between Microsoft DLLs and
832 Unix shared libraries, is the fact that on most Unix systems all public
833 routines are exported by default in a Unix shared library, while under
834 Windows it is possible (but not required) to list exported routines in
835 a definition file (see :ref:`The Definition File <The_Definition_File>`).
836
837
838 .. _Using_DLLs_with_GNAT:
839
840 Using DLLs with GNAT
841 ^^^^^^^^^^^^^^^^^^^^
842
843 To use the services of a DLL, say :file:`API.dll`, in your Ada application
844 you must have:
845
846 * The Ada spec for the routines and/or variables you want to access in
847 :file:`API.dll`. If not available this Ada spec must be built from the C/C++
848 header files provided with the DLL.
849
850 * The import library (:file:`libAPI.dll.a` or :file:`API.lib`). As previously
851 mentioned an import library is a statically linked library containing the
852 import table which will be filled at load time to point to the actual
853 :file:`API.dll` routines. Sometimes you don't have an import library for the
854 DLL you want to use. The following sections will explain how to build
855 one. Note that this is optional.
856
857 * The actual DLL, :file:`API.dll`.
858
859 Once you have all the above, to compile an Ada application that uses the
860 services of :file:`API.dll` and whose main subprogram is ``My_Ada_App``,
861 you simply issue the command
862
863 ::
864
865 $ gnatmake my_ada_app -largs -lAPI
866
867 The argument :switch:`-largs -lAPI` at the end of the ``gnatmake`` command
868 tells the GNAT linker to look for an import library. The linker will
869 look for a library name in this specific order:
870
871 * :file:`libAPI.dll.a`
872 * :file:`API.dll.a`
873 * :file:`libAPI.a`
874 * :file:`API.lib`
875 * :file:`libAPI.dll`
876 * :file:`API.dll`
877
878 The first three are the GNU style import libraries. The third is the
879 Microsoft style import libraries. The last two are the actual DLL names.
880
881 Note that if the Ada package spec for :file:`API.dll` contains the
882 following pragma
883
884 .. code-block:: ada
885
886 pragma Linker_Options ("-lAPI");
887
888 you do not have to add :switch:`-largs -lAPI` at the end of the
889 ``gnatmake`` command.
890
891 If any one of the items above is missing you will have to create it
892 yourself. The following sections explain how to do so using as an
893 example a fictitious DLL called :file:`API.dll`.
894
895
896 .. _Creating_an_Ada_Spec_for_the_DLL_Services:
897
898 Creating an Ada Spec for the DLL Services
899 """""""""""""""""""""""""""""""""""""""""
900
901 A DLL typically comes with a C/C++ header file which provides the
902 definitions of the routines and variables exported by the DLL. The Ada
903 equivalent of this header file is a package spec that contains definitions
904 for the imported entities. If the DLL you intend to use does not come with
905 an Ada spec you have to generate one such spec yourself. For example if
906 the header file of :file:`API.dll` is a file :file:`api.h` containing the
907 following two definitions:
908
909 .. code-block:: c
910
911 int some_var;
912 int get (char *);
913
914 then the equivalent Ada spec could be:
915
916 .. code-block:: ada
917
918 with Interfaces.C.Strings;
919 package API is
920 use Interfaces;
921
922 Some_Var : C.int;
923 function Get (Str : C.Strings.Chars_Ptr) return C.int;
924
925 private
926 pragma Import (C, Get);
927 pragma Import (DLL, Some_Var);
928 end API;
929
930
931 .. _Creating_an_Import_Library:
932
933 Creating an Import Library
934 """"""""""""""""""""""""""
935
936 .. index:: Import library
937
938 If a Microsoft-style import library :file:`API.lib` or a GNAT-style
939 import library :file:`libAPI.dll.a` or :file:`libAPI.a` is available
940 with :file:`API.dll` you can skip this section. You can also skip this
941 section if :file:`API.dll` or :file:`libAPI.dll` is built with GNU tools
942 as in this case it is possible to link directly against the
943 DLL. Otherwise read on.
944
945
946 .. index:: Definition file
947
948 .. _The_Definition_File:
949
950 .. rubric:: The Definition File
951
952 As previously mentioned, and unlike Unix systems, the list of symbols
953 that are exported from a DLL must be provided explicitly in Windows.
954 The main goal of a definition file is precisely that: list the symbols
955 exported by a DLL. A definition file (usually a file with a ``.def``
956 suffix) has the following structure:
957
958 ::
959
960 [LIBRARY ``name``]
961 [DESCRIPTION ``string``]
962 EXPORTS
963 ``symbol1``
964 ``symbol2``
965 ...
966
967 *LIBRARY name*
968 This section, which is optional, gives the name of the DLL.
969
970
971 *DESCRIPTION string*
972 This section, which is optional, gives a description string that will be
973 embedded in the import library.
974
975
976 *EXPORTS*
977 This section gives the list of exported symbols (procedures, functions or
978 variables). For instance in the case of :file:`API.dll` the ``EXPORTS``
979 section of :file:`API.def` looks like:
980
981 ::
982
983 EXPORTS
984 some_var
985 get
986
987 Note that you must specify the correct suffix (:samp:`@{nn}`)
988 (see :ref:`Windows_Calling_Conventions`) for a Stdcall
989 calling convention function in the exported symbols list.
990
991 There can actually be other sections in a definition file, but these
992 sections are not relevant to the discussion at hand.
993
994
995 .. _Create_Def_File_Automatically:
996
997 .. rubric:: Creating a Definition File Automatically
998
999 You can automatically create the definition file :file:`API.def`
1000 (see :ref:`The Definition File <The_Definition_File>`) from a DLL.
1001 For that use the ``dlltool`` program as follows:
1002
1003 ::
1004
1005 $ dlltool API.dll -z API.def --export-all-symbols
1006
1007 Note that if some routines in the DLL have the ``Stdcall`` convention
1008 (:ref:`Windows_Calling_Conventions`) with stripped :samp:`@{nn}`
1009 suffix then you'll have to edit :file:`api.def` to add it, and specify
1010 :switch:`-k` to ``gnatdll`` when creating the import library.
1011
1012 Here are some hints to find the right :samp:`@{nn}` suffix.
1013
1014 - If you have the Microsoft import library (.lib), it is possible to get
1015 the right symbols by using Microsoft ``dumpbin`` tool (see the
1016 corresponding Microsoft documentation for further details).
1017
1018 ::
1019
1020 $ dumpbin /exports api.lib
1021
1022 - If you have a message about a missing symbol at link time the compiler
1023 tells you what symbol is expected. You just have to go back to the
1024 definition file and add the right suffix.
1025
1026
1027 .. _GNAT-Style_Import_Library:
1028
1029 .. rubric:: GNAT-Style Import Library
1030
1031 To create a static import library from :file:`API.dll` with the GNAT tools
1032 you should create the .def file, then use ``gnatdll`` tool
1033 (see :ref:`Using_gnatdll`) as follows:
1034
1035 ::
1036
1037 $ gnatdll -e API.def -d API.dll
1038
1039 ``gnatdll`` takes as input a definition file :file:`API.def` and the
1040 name of the DLL containing the services listed in the definition file
1041 :file:`API.dll`. The name of the static import library generated is
1042 computed from the name of the definition file as follows: if the
1043 definition file name is :file:`xyz.def`, the import library name will
1044 be :file:`libxyz.a`. Note that in the previous example option
1045 :switch:`-e` could have been removed because the name of the definition
1046 file (before the ``.def`` suffix) is the same as the name of the
1047 DLL (:ref:`Using_gnatdll` for more information about ``gnatdll``).
1048
1049
1050 .. _MSVS-Style_Import_Library:
1051
1052 .. rubric:: Microsoft-Style Import Library
1053
1054 A Microsoft import library is needed only if you plan to make an
1055 Ada DLL available to applications developed with Microsoft
1056 tools (:ref:`Mixed-Language_Programming_on_Windows`).
1057
1058 To create a Microsoft-style import library for :file:`API.dll` you
1059 should create the .def file, then build the actual import library using
1060 Microsoft's ``lib`` utility:
1061
1062 ::
1063
1064 $ lib -machine:IX86 -def:API.def -out:API.lib
1065
1066 If you use the above command the definition file :file:`API.def` must
1067 contain a line giving the name of the DLL:
1068
1069 ::
1070
1071 LIBRARY "API"
1072
1073 See the Microsoft documentation for further details about the usage of
1074 ``lib``.
1075
1076
1077 .. _Building_DLLs_with_GNAT_Project_files:
1078
1079 Building DLLs with GNAT Project files
1080 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
1081
1082 .. index:: DLLs, building
1083
1084 There is nothing specific to Windows in the build process.
1085 See the *Library Projects* section in the *GNAT Project Manager*
1086 chapter of the *GPRbuild User's Guide*.
1087
1088 Due to a system limitation, it is not possible under Windows to create threads
1089 when inside the ``DllMain`` routine which is used for auto-initialization
1090 of shared libraries, so it is not possible to have library level tasks in SALs.
1091
1092
1093 .. _Building_DLLs_with_GNAT:
1094
1095 Building DLLs with GNAT
1096 ^^^^^^^^^^^^^^^^^^^^^^^
1097
1098 .. index:: DLLs, building
1099
1100 This section explain how to build DLLs using the GNAT built-in DLL
1101 support. With the following procedure it is straight forward to build
1102 and use DLLs with GNAT.
1103
1104
1105 * Building object files.
1106 The first step is to build all objects files that are to be included
1107 into the DLL. This is done by using the standard ``gnatmake`` tool.
1108
1109 * Building the DLL.
1110 To build the DLL you must use the ``gcc`` :switch:`-shared` and
1111 :switch:`-shared-libgcc` options. It is quite simple to use this method:
1112
1113 ::
1114
1115 $ gcc -shared -shared-libgcc -o api.dll obj1.o obj2.o ...
1116
1117 It is important to note that in this case all symbols found in the
1118 object files are automatically exported. It is possible to restrict
1119 the set of symbols to export by passing to ``gcc`` a definition
1120 file (see :ref:`The Definition File <The_Definition_File>`).
1121 For example:
1122
1123 ::
1124
1125 $ gcc -shared -shared-libgcc -o api.dll api.def obj1.o obj2.o ...
1126
1127 If you use a definition file you must export the elaboration procedures
1128 for every package that required one. Elaboration procedures are named
1129 using the package name followed by "_E".
1130
1131 * Preparing DLL to be used.
1132 For the DLL to be used by client programs the bodies must be hidden
1133 from it and the .ali set with read-only attribute. This is very important
1134 otherwise GNAT will recompile all packages and will not actually use
1135 the code in the DLL. For example:
1136
1137 ::
1138
1139 $ mkdir apilib
1140 $ copy *.ads *.ali api.dll apilib
1141 $ attrib +R apilib\\*.ali
1142
1143 At this point it is possible to use the DLL by directly linking
1144 against it. Note that you must use the GNAT shared runtime when using
1145 GNAT shared libraries. This is achieved by using the :switch:`-shared` binder
1146 option.
1147
1148 ::
1149
1150 $ gnatmake main -Iapilib -bargs -shared -largs -Lapilib -lAPI
1151
1152
1153 .. _Building_DLLs_with_gnatdll:
1154
1155 Building DLLs with gnatdll
1156 ^^^^^^^^^^^^^^^^^^^^^^^^^^
1157
1158 .. index:: DLLs, building
1159
1160 Note that it is preferred to use GNAT Project files
1161 (:ref:`Building_DLLs_with_GNAT_Project_files`) or the built-in GNAT
1162 DLL support (:ref:`Building_DLLs_with_GNAT`) or to build DLLs.
1163
1164 This section explains how to build DLLs containing Ada code using
1165 ``gnatdll``. These DLLs will be referred to as Ada DLLs in the
1166 remainder of this section.
1167
1168 The steps required to build an Ada DLL that is to be used by Ada as well as
1169 non-Ada applications are as follows:
1170
1171 * You need to mark each Ada entity exported by the DLL with a ``C`` or
1172 ``Stdcall`` calling convention to avoid any Ada name mangling for the
1173 entities exported by the DLL
1174 (see :ref:`Exporting Ada Entities <Exporting_Ada_Entities>`). You can
1175 skip this step if you plan to use the Ada DLL only from Ada applications.
1176
1177 * Your Ada code must export an initialization routine which calls the routine
1178 ``adainit`` generated by ``gnatbind`` to perform the elaboration of
1179 the Ada code in the DLL (:ref:`Ada_DLLs_and_Elaboration`). The initialization
1180 routine exported by the Ada DLL must be invoked by the clients of the DLL
1181 to initialize the DLL.
1182
1183 * When useful, the DLL should also export a finalization routine which calls
1184 routine ``adafinal`` generated by ``gnatbind`` to perform the
1185 finalization of the Ada code in the DLL (:ref:`Ada_DLLs_and_Finalization`).
1186 The finalization routine exported by the Ada DLL must be invoked by the
1187 clients of the DLL when the DLL services are no further needed.
1188
1189 * You must provide a spec for the services exported by the Ada DLL in each
1190 of the programming languages to which you plan to make the DLL available.
1191
1192 * You must provide a definition file listing the exported entities
1193 (:ref:`The Definition File <The_Definition_File>`).
1194
1195 * Finally you must use ``gnatdll`` to produce the DLL and the import
1196 library (:ref:`Using_gnatdll`).
1197
1198 Note that a relocatable DLL stripped using the ``strip``
1199 binutils tool will not be relocatable anymore. To build a DLL without
1200 debug information pass :switch:`-largs -s` to ``gnatdll``. This
1201 restriction does not apply to a DLL built using a Library Project.
1202 See the *Library Projects* section in the *GNAT Project Manager*
1203 chapter of the *GPRbuild User's Guide*.
1204
1205
1206 .. Limitations_When_Using_Ada_DLLs_from Ada:
1207
1208 Limitations When Using Ada DLLs from Ada
1209 """"""""""""""""""""""""""""""""""""""""
1210
1211 When using Ada DLLs from Ada applications there is a limitation users
1212 should be aware of. Because on Windows the GNAT run-time is not in a DLL of
1213 its own, each Ada DLL includes a part of the GNAT run-time. Specifically,
1214 each Ada DLL includes the services of the GNAT run-time that are necessary
1215 to the Ada code inside the DLL. As a result, when an Ada program uses an
1216 Ada DLL there are two independent GNAT run-times: one in the Ada DLL and
1217 one in the main program.
1218
1219 It is therefore not possible to exchange GNAT run-time objects between the
1220 Ada DLL and the main Ada program. Example of GNAT run-time objects are file
1221 handles (e.g., ``Text_IO.File_Type``), tasks types, protected objects
1222 types, etc.
1223
1224 It is completely safe to exchange plain elementary, array or record types,
1225 Windows object handles, etc.
1226
1227
1228 .. _Exporting_Ada_Entities:
1229
1230 Exporting Ada Entities
1231 """"""""""""""""""""""
1232
1233 .. index:: Export table
1234
1235 Building a DLL is a way to encapsulate a set of services usable from any
1236 application. As a result, the Ada entities exported by a DLL should be
1237 exported with the ``C`` or ``Stdcall`` calling conventions to avoid
1238 any Ada name mangling. As an example here is an Ada package
1239 ``API``, spec and body, exporting two procedures, a function, and a
1240 variable:
1241
1242
1243 .. code-block:: ada
1244
1245 with Interfaces.C; use Interfaces;
1246 package API is
1247 Count : C.int := 0;
1248 function Factorial (Val : C.int) return C.int;
1249
1250 procedure Initialize_API;
1251 procedure Finalize_API;
1252 -- Initialization & Finalization routines. More in the next section.
1253 private
1254 pragma Export (C, Initialize_API);
1255 pragma Export (C, Finalize_API);
1256 pragma Export (C, Count);
1257 pragma Export (C, Factorial);
1258 end API;
1259
1260 .. code-block:: ada
1261
1262 package body API is
1263 function Factorial (Val : C.int) return C.int is
1264 Fact : C.int := 1;
1265 begin
1266 Count := Count + 1;
1267 for K in 1 .. Val loop
1268 Fact := Fact * K;
1269 end loop;
1270 return Fact;
1271 end Factorial;
1272
1273 procedure Initialize_API is
1274 procedure Adainit;
1275 pragma Import (C, Adainit);
1276 begin
1277 Adainit;
1278 end Initialize_API;
1279
1280 procedure Finalize_API is
1281 procedure Adafinal;
1282 pragma Import (C, Adafinal);
1283 begin
1284 Adafinal;
1285 end Finalize_API;
1286 end API;
1287
1288 If the Ada DLL you are building will only be used by Ada applications
1289 you do not have to export Ada entities with a ``C`` or ``Stdcall``
1290 convention. As an example, the previous package could be written as
1291 follows:
1292
1293 .. code-block:: ada
1294
1295 package API is
1296 Count : Integer := 0;
1297 function Factorial (Val : Integer) return Integer;
1298
1299 procedure Initialize_API;
1300 procedure Finalize_API;
1301 -- Initialization and Finalization routines.
1302 end API;
1303
1304 .. code-block:: ada
1305
1306 package body API is
1307 function Factorial (Val : Integer) return Integer is
1308 Fact : Integer := 1;
1309 begin
1310 Count := Count + 1;
1311 for K in 1 .. Val loop
1312 Fact := Fact * K;
1313 end loop;
1314 return Fact;
1315 end Factorial;
1316
1317 ...
1318 -- The remainder of this package body is unchanged.
1319 end API;
1320
1321 Note that if you do not export the Ada entities with a ``C`` or
1322 ``Stdcall`` convention you will have to provide the mangled Ada names
1323 in the definition file of the Ada DLL
1324 (:ref:`Creating_the_Definition_File`).
1325
1326
1327 .. _Ada_DLLs_and_Elaboration:
1328
1329 Ada DLLs and Elaboration
1330 """"""""""""""""""""""""
1331
1332 .. index:: DLLs and elaboration
1333
1334 The DLL that you are building contains your Ada code as well as all the
1335 routines in the Ada library that are needed by it. The first thing a
1336 user of your DLL must do is elaborate the Ada code
1337 (:ref:`Elaboration_Order_Handling_in_GNAT`).
1338
1339 To achieve this you must export an initialization routine
1340 (``Initialize_API`` in the previous example), which must be invoked
1341 before using any of the DLL services. This elaboration routine must call
1342 the Ada elaboration routine ``adainit`` generated by the GNAT binder
1343 (:ref:`Binding_with_Non-Ada_Main_Programs`). See the body of
1344 ``Initialize_Api`` for an example. Note that the GNAT binder is
1345 automatically invoked during the DLL build process by the ``gnatdll``
1346 tool (:ref:`Using_gnatdll`).
1347
1348 When a DLL is loaded, Windows systematically invokes a routine called
1349 ``DllMain``. It would therefore be possible to call ``adainit``
1350 directly from ``DllMain`` without having to provide an explicit
1351 initialization routine. Unfortunately, it is not possible to call
1352 ``adainit`` from the ``DllMain`` if your program has library level
1353 tasks because access to the ``DllMain`` entry point is serialized by
1354 the system (that is, only a single thread can execute 'through' it at a
1355 time), which means that the GNAT run-time will deadlock waiting for the
1356 newly created task to complete its initialization.
1357
1358
1359 .. _Ada_DLLs_and_Finalization:
1360
1361 Ada DLLs and Finalization
1362 ^^^^^^^^^^^^^^^^^^^^^^^^^
1363
1364 .. index:: DLLs and finalization
1365
1366 When the services of an Ada DLL are no longer needed, the client code should
1367 invoke the DLL finalization routine, if available. The DLL finalization
1368 routine is in charge of releasing all resources acquired by the DLL. In the
1369 case of the Ada code contained in the DLL, this is achieved by calling
1370 routine ``adafinal`` generated by the GNAT binder
1371 (:ref:`Binding_with_Non-Ada_Main_Programs`).
1372 See the body of ``Finalize_Api`` for an
1373 example. As already pointed out the GNAT binder is automatically invoked
1374 during the DLL build process by the ``gnatdll`` tool
1375 (:ref:`Using_gnatdll`).
1376
1377
1378 .. _Creating_a_Spec_for_Ada_DLLs:
1379
1380 Creating a Spec for Ada DLLs
1381 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
1382
1383 To use the services exported by the Ada DLL from another programming
1384 language (e.g., C), you have to translate the specs of the exported Ada
1385 entities in that language. For instance in the case of ``API.dll``,
1386 the corresponding C header file could look like:
1387
1388 .. code-block:: c
1389
1390 extern int *_imp__count;
1391 #define count (*_imp__count)
1392 int factorial (int);
1393
1394 It is important to understand that when building an Ada DLL to be used by
1395 other Ada applications, you need two different specs for the packages
1396 contained in the DLL: one for building the DLL and the other for using
1397 the DLL. This is because the ``DLL`` calling convention is needed to
1398 use a variable defined in a DLL, but when building the DLL, the variable
1399 must have either the ``Ada`` or ``C`` calling convention. As an
1400 example consider a DLL comprising the following package ``API``:
1401
1402 .. code-block:: ada
1403
1404 package API is
1405 Count : Integer := 0;
1406 ...
1407 -- Remainder of the package omitted.
1408 end API;
1409
1410 After producing a DLL containing package ``API``, the spec that
1411 must be used to import ``API.Count`` from Ada code outside of the
1412 DLL is:
1413
1414 .. code-block:: ada
1415
1416 package API is
1417 Count : Integer;
1418 pragma Import (DLL, Count);
1419 end API;
1420
1421
1422 .. _Creating_the_Definition_File:
1423
1424 Creating the Definition File
1425 """"""""""""""""""""""""""""
1426
1427 The definition file is the last file needed to build the DLL. It lists
1428 the exported symbols. As an example, the definition file for a DLL
1429 containing only package ``API`` (where all the entities are exported
1430 with a ``C`` calling convention) is:
1431
1432 ::
1433
1434 EXPORTS
1435 count
1436 factorial
1437 finalize_api
1438 initialize_api
1439
1440 If the ``C`` calling convention is missing from package ``API``,
1441 then the definition file contains the mangled Ada names of the above
1442 entities, which in this case are:
1443
1444 ::
1445
1446 EXPORTS
1447 api__count
1448 api__factorial
1449 api__finalize_api
1450 api__initialize_api
1451
1452
1453 .. _Using_gnatdll:
1454
1455 Using ``gnatdll``
1456 """""""""""""""""
1457
1458 .. index:: gnatdll
1459
1460 ``gnatdll`` is a tool to automate the DLL build process once all the Ada
1461 and non-Ada sources that make up your DLL have been compiled.
1462 ``gnatdll`` is actually in charge of two distinct tasks: build the
1463 static import library for the DLL and the actual DLL. The form of the
1464 ``gnatdll`` command is
1465
1466 ::
1467
1468 $ gnatdll [ switches ] list-of-files [ -largs opts ]
1469
1470 where ``list-of-files`` is a list of ALI and object files. The object
1471 file list must be the exact list of objects corresponding to the non-Ada
1472 sources whose services are to be included in the DLL. The ALI file list
1473 must be the exact list of ALI files for the corresponding Ada sources
1474 whose services are to be included in the DLL. If ``list-of-files`` is
1475 missing, only the static import library is generated.
1476
1477 You may specify any of the following switches to ``gnatdll``:
1478
1479
1480 .. index:: -a (gnatdll)
1481
1482 :switch:`-a[{address}]`
1483 Build a non-relocatable DLL at ``address``. If ``address`` is not
1484 specified the default address ``0x11000000`` will be used. By default,
1485 when this switch is missing, ``gnatdll`` builds relocatable DLL. We
1486 advise the reader to build relocatable DLL.
1487
1488
1489 .. index:: -b (gnatdll)
1490
1491 :switch:`-b {address}`
1492 Set the relocatable DLL base address. By default the address is
1493 ``0x11000000``.
1494
1495
1496 .. index:: -bargs (gnatdll)
1497
1498 :switch:`-bargs {opts}`
1499 Binder options. Pass ``opts`` to the binder.
1500
1501
1502 .. index:: -d (gnatdll)
1503
1504 :switch:`-d {dllfile}`
1505 ``dllfile`` is the name of the DLL. This switch must be present for
1506 ``gnatdll`` to do anything. The name of the generated import library is
1507 obtained algorithmically from ``dllfile`` as shown in the following
1508 example: if ``dllfile`` is :file:`xyz.dll`, the import library name is
1509 :file:`libxyz.dll.a`. The name of the definition file to use (if not specified
1510 by option :switch:`-e`) is obtained algorithmically from ``dllfile``
1511 as shown in the following example:
1512 if ``dllfile`` is :file:`xyz.dll`, the definition
1513 file used is :file:`xyz.def`.
1514
1515
1516 .. index:: -e (gnatdll)
1517
1518 :switch:`-e {deffile}`
1519 ``deffile`` is the name of the definition file.
1520
1521
1522 .. index:: -g (gnatdll)
1523
1524 :switch:`-g`
1525 Generate debugging information. This information is stored in the object
1526 file and copied from there to the final DLL file by the linker,
1527 where it can be read by the debugger. You must use the
1528 :switch:`-g` switch if you plan on using the debugger or the symbolic
1529 stack traceback.
1530
1531
1532 .. index:: -h (gnatdll)
1533
1534 :switch:`-h`
1535 Help mode. Displays ``gnatdll`` switch usage information.
1536
1537
1538 .. index:: -I (gnatdll)
1539
1540 :switch:`-I{dir}`
1541 Direct ``gnatdll`` to search the ``dir`` directory for source and
1542 object files needed to build the DLL.
1543 (:ref:`Search_Paths_and_the_Run-Time_Library_RTL`).
1544
1545
1546 .. index:: -k (gnatdll)
1547
1548 :switch:`-k`
1549 Removes the :samp:`@{nn}` suffix from the import library's exported
1550 names, but keeps them for the link names. You must specify this
1551 option if you want to use a ``Stdcall`` function in a DLL for which
1552 the :samp:`@{nn}` suffix has been removed. This is the case for most
1553 of the Windows NT DLL for example. This option has no effect when
1554 :switch:`-n` option is specified.
1555
1556
1557 .. index:: -l (gnatdll)
1558
1559 :switch:`-l {file}`
1560 The list of ALI and object files used to build the DLL are listed in
1561 ``file``, instead of being given in the command line. Each line in
1562 ``file`` contains the name of an ALI or object file.
1563
1564
1565 .. index:: -n (gnatdll)
1566
1567 :switch:`-n`
1568 No Import. Do not create the import library.
1569
1570
1571 .. index:: -q (gnatdll)
1572
1573 :switch:`-q`
1574 Quiet mode. Do not display unnecessary messages.
1575
1576
1577 .. index:: -v (gnatdll)
1578
1579 :switch:`-v`
1580 Verbose mode. Display extra information.
1581
1582
1583 .. index:: -largs (gnatdll)
1584
1585 :switch:`-largs {opts}`
1586 Linker options. Pass ``opts`` to the linker.
1587
1588
1589 .. rubric:: ``gnatdll`` Example
1590
1591 As an example the command to build a relocatable DLL from :file:`api.adb`
1592 once :file:`api.adb` has been compiled and :file:`api.def` created is
1593
1594 ::
1595
1596 $ gnatdll -d api.dll api.ali
1597
1598 The above command creates two files: :file:`libapi.dll.a` (the import
1599 library) and :file:`api.dll` (the actual DLL). If you want to create
1600 only the DLL, just type:
1601
1602 ::
1603
1604 $ gnatdll -d api.dll -n api.ali
1605
1606 Alternatively if you want to create just the import library, type:
1607
1608 ::
1609
1610 $ gnatdll -d api.dll
1611
1612
1613 .. rubric:: ``gnatdll`` behind the Scenes
1614
1615 This section details the steps involved in creating a DLL. ``gnatdll``
1616 does these steps for you. Unless you are interested in understanding what
1617 goes on behind the scenes, you should skip this section.
1618
1619 We use the previous example of a DLL containing the Ada package ``API``,
1620 to illustrate the steps necessary to build a DLL. The starting point is a
1621 set of objects that will make up the DLL and the corresponding ALI
1622 files. In the case of this example this means that :file:`api.o` and
1623 :file:`api.ali` are available. To build a relocatable DLL, ``gnatdll`` does
1624 the following:
1625
1626 * ``gnatdll`` builds the base file (:file:`api.base`). A base file gives
1627 the information necessary to generate relocation information for the
1628 DLL.
1629
1630 ::
1631
1632 $ gnatbind -n api
1633 $ gnatlink api -o api.jnk -mdll -Wl,--base-file,api.base
1634
1635 In addition to the base file, the ``gnatlink`` command generates an
1636 output file :file:`api.jnk` which can be discarded. The :switch:`-mdll` switch
1637 asks ``gnatlink`` to generate the routines ``DllMain`` and
1638 ``DllMainCRTStartup`` that are called by the Windows loader when the DLL
1639 is loaded into memory.
1640
1641 * ``gnatdll`` uses ``dlltool`` (see :ref:`Using dlltool <Using_dlltool>`) to build the
1642 export table (:file:`api.exp`). The export table contains the relocation
1643 information in a form which can be used during the final link to ensure
1644 that the Windows loader is able to place the DLL anywhere in memory.
1645
1646 ::
1647
1648 $ dlltool --dllname api.dll --def api.def --base-file api.base \\
1649 --output-exp api.exp
1650
1651 * ``gnatdll`` builds the base file using the new export table. Note that
1652 ``gnatbind`` must be called once again since the binder generated file
1653 has been deleted during the previous call to ``gnatlink``.
1654
1655 ::
1656
1657 $ gnatbind -n api
1658 $ gnatlink api -o api.jnk api.exp -mdll
1659 -Wl,--base-file,api.base
1660
1661
1662 * ``gnatdll`` builds the new export table using the new base file and
1663 generates the DLL import library :file:`libAPI.dll.a`.
1664
1665
1666 ::
1667
1668 $ dlltool --dllname api.dll --def api.def --base-file api.base \\
1669 --output-exp api.exp --output-lib libAPI.a
1670
1671 * Finally ``gnatdll`` builds the relocatable DLL using the final export
1672 table.
1673
1674 ::
1675
1676 $ gnatbind -n api
1677 $ gnatlink api api.exp -o api.dll -mdll
1678
1679
1680 .. _Using_dlltool:
1681
1682 .. rubric:: Using ``dlltool``
1683
1684 ``dlltool`` is the low-level tool used by ``gnatdll`` to build
1685 DLLs and static import libraries. This section summarizes the most
1686 common ``dlltool`` switches. The form of the ``dlltool`` command
1687 is
1688
1689 ::
1690
1691 $ dlltool [`switches`]
1692
1693 ``dlltool`` switches include:
1694
1695
1696 .. index:: --base-file (dlltool)
1697
1698 :switch:`--base-file {basefile}`
1699 Read the base file ``basefile`` generated by the linker. This switch
1700 is used to create a relocatable DLL.
1701
1702
1703 .. index:: --def (dlltool)
1704
1705 :switch:`--def {deffile}`
1706 Read the definition file.
1707
1708
1709 .. index:: --dllname (dlltool)
1710
1711 :switch:`--dllname {name}`
1712 Gives the name of the DLL. This switch is used to embed the name of the
1713 DLL in the static import library generated by ``dlltool`` with switch
1714 :switch:`--output-lib`.
1715
1716
1717 .. index:: -k (dlltool)
1718
1719 :switch:`-k`
1720 Kill :samp:`@{nn}` from exported names
1721 (:ref:`Windows_Calling_Conventions`
1722 for a discussion about ``Stdcall``-style symbols).
1723
1724
1725 .. index:: --help (dlltool)
1726
1727 :switch:`--help`
1728 Prints the ``dlltool`` switches with a concise description.
1729
1730
1731 .. index:: --output-exp (dlltool)
1732
1733 :switch:`--output-exp {exportfile}`
1734 Generate an export file ``exportfile``. The export file contains the
1735 export table (list of symbols in the DLL) and is used to create the DLL.
1736
1737
1738 .. index:: --output-lib (dlltool)
1739
1740 :switch:`--output-lib {libfile}`
1741 Generate a static import library ``libfile``.
1742
1743
1744 .. index:: -v (dlltool)
1745
1746 :switch:`-v`
1747 Verbose mode.
1748
1749
1750 .. index:: --as (dlltool)
1751
1752 :switch:`--as {assembler-name}`
1753 Use ``assembler-name`` as the assembler. The default is ``as``.
1754
1755
1756 .. _GNAT_and_Windows_Resources:
1757
1758 GNAT and Windows Resources
1759 ^^^^^^^^^^^^^^^^^^^^^^^^^^
1760
1761 .. index:: Resources, windows
1762
1763 Resources are an easy way to add Windows specific objects to your
1764 application. The objects that can be added as resources include:
1765
1766 * menus
1767
1768 * accelerators
1769
1770 * dialog boxes
1771
1772 * string tables
1773
1774 * bitmaps
1775
1776 * cursors
1777
1778 * icons
1779
1780 * fonts
1781
1782 * version information
1783
1784 For example, a version information resource can be defined as follow and
1785 embedded into an executable or DLL:
1786
1787 A version information resource can be used to embed information into an
1788 executable or a DLL. These information can be viewed using the file properties
1789 from the Windows Explorer. Here is an example of a version information
1790 resource:
1791
1792 ::
1793
1794 1 VERSIONINFO
1795 FILEVERSION 1,0,0,0
1796 PRODUCTVERSION 1,0,0,0
1797 BEGIN
1798 BLOCK "StringFileInfo"
1799 BEGIN
1800 BLOCK "080904E4"
1801 BEGIN
1802 VALUE "CompanyName", "My Company Name"
1803 VALUE "FileDescription", "My application"
1804 VALUE "FileVersion", "1.0"
1805 VALUE "InternalName", "my_app"
1806 VALUE "LegalCopyright", "My Name"
1807 VALUE "OriginalFilename", "my_app.exe"
1808 VALUE "ProductName", "My App"
1809 VALUE "ProductVersion", "1.0"
1810 END
1811 END
1812
1813 BLOCK "VarFileInfo"
1814 BEGIN
1815 VALUE "Translation", 0x809, 1252
1816 END
1817 END
1818
1819 The value ``0809`` (langID) is for the U.K English language and
1820 ``04E4`` (charsetID), which is equal to ``1252`` decimal, for
1821 multilingual.
1822
1823 This section explains how to build, compile and use resources. Note that this
1824 section does not cover all resource objects, for a complete description see
1825 the corresponding Microsoft documentation.
1826
1827
1828 .. _Building_Resources:
1829
1830 Building Resources
1831 """"""""""""""""""
1832
1833 .. index:: Resources, building
1834
1835 A resource file is an ASCII file. By convention resource files have an
1836 :file:`.rc` extension.
1837 The easiest way to build a resource file is to use Microsoft tools
1838 such as ``imagedit.exe`` to build bitmaps, icons and cursors and
1839 ``dlgedit.exe`` to build dialogs.
1840 It is always possible to build an :file:`.rc` file yourself by writing a
1841 resource script.
1842
1843 It is not our objective to explain how to write a resource file. A
1844 complete description of the resource script language can be found in the
1845 Microsoft documentation.
1846
1847
1848 .. _Compiling_Resources:
1849
1850 Compiling Resources
1851 """""""""""""""""""
1852
1853 .. index:: rc
1854 .. index:: windres
1855 .. index:: Resources, compiling
1856
1857 This section describes how to build a GNAT-compatible (COFF) object file
1858 containing the resources. This is done using the Resource Compiler
1859 ``windres`` as follows:
1860
1861 ::
1862
1863 $ windres -i myres.rc -o myres.o
1864
1865 By default ``windres`` will run ``gcc`` to preprocess the :file:`.rc`
1866 file. You can specify an alternate preprocessor (usually named
1867 :file:`cpp.exe`) using the ``windres`` :switch:`--preprocessor`
1868 parameter. A list of all possible options may be obtained by entering
1869 the command ``windres`` :switch:`--help`.
1870
1871 It is also possible to use the Microsoft resource compiler ``rc.exe``
1872 to produce a :file:`.res` file (binary resource file). See the
1873 corresponding Microsoft documentation for further details. In this case
1874 you need to use ``windres`` to translate the :file:`.res` file to a
1875 GNAT-compatible object file as follows:
1876
1877 ::
1878
1879 $ windres -i myres.res -o myres.o
1880
1881
1882 .. _Using_Resources:
1883
1884 Using Resources
1885 """""""""""""""
1886
1887 .. index:: Resources, using
1888
1889 To include the resource file in your program just add the
1890 GNAT-compatible object file for the resource(s) to the linker
1891 arguments. With ``gnatmake`` this is done by using the :switch:`-largs`
1892 option:
1893
1894 ::
1895
1896 $ gnatmake myprog -largs myres.o
1897
1898
1899 .. _Using_GNAT_DLL_from_MSVS:
1900
1901 Using GNAT DLLs from Microsoft Visual Studio Applications
1902 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
1903
1904 .. index:: Microsoft Visual Studio, use with GNAT DLLs
1905
1906 This section describes a common case of mixed GNAT/Microsoft Visual Studio
1907 application development, where the main program is developed using MSVS, and
1908 is linked with a DLL developed using GNAT. Such a mixed application should
1909 be developed following the general guidelines outlined above; below is the
1910 cookbook-style sequence of steps to follow:
1911
1912 1. First develop and build the GNAT shared library using a library project
1913 (let's assume the project is :file:`mylib.gpr`, producing the library :file:`libmylib.dll`):
1914
1915 ::
1916
1917 $ gprbuild -p mylib.gpr
1918
1919 2. Produce a .def file for the symbols you need to interface with, either by
1920 hand or automatically with possibly some manual adjustments
1921 (see :ref:`Creating Definition File Automatically <Create_Def_File_Automatically>`):
1922
1923 ::
1924
1925 $ dlltool libmylib.dll -z libmylib.def --export-all-symbols
1926
1927 3. Make sure that MSVS command-line tools are accessible on the path.
1928
1929 4. Create the Microsoft-style import library (see :ref:`MSVS-Style Import Library <MSVS-Style_Import_Library>`):
1930
1931 ::
1932
1933 $ lib -machine:IX86 -def:libmylib.def -out:libmylib.lib
1934
1935 If you are using a 64-bit toolchain, the above becomes...
1936
1937 ::
1938
1939 $ lib -machine:X64 -def:libmylib.def -out:libmylib.lib
1940
1941 5. Build the C main
1942
1943 ::
1944
1945 $ cl /O2 /MD main.c libmylib.lib
1946
1947 6. Before running the executable, make sure you have set the PATH to the DLL,
1948 or copy the DLL into into the directory containing the .exe.
1949
1950
1951 .. _Debugging_a_DLL:
1952
1953 Debugging a DLL
1954 ^^^^^^^^^^^^^^^
1955
1956 .. index:: DLL debugging
1957
1958 Debugging a DLL is similar to debugging a standard program. But
1959 we have to deal with two different executable parts: the DLL and the
1960 program that uses it. We have the following four possibilities:
1961
1962 * The program and the DLL are built with GCC/GNAT.
1963 * The program is built with foreign tools and the DLL is built with
1964 GCC/GNAT.
1965 * The program is built with GCC/GNAT and the DLL is built with
1966 foreign tools.
1967
1968 In this section we address only cases one and two above.
1969 There is no point in trying to debug
1970 a DLL with GNU/GDB, if there is no GDB-compatible debugging
1971 information in it. To do so you must use a debugger compatible with the
1972 tools suite used to build the DLL.
1973
1974 .. _Program_and_DLL_Both_Built_with_GCC/GNAT:
1975
1976 Program and DLL Both Built with GCC/GNAT
1977 """"""""""""""""""""""""""""""""""""""""
1978
1979 This is the simplest case. Both the DLL and the program have ``GDB``
1980 compatible debugging information. It is then possible to break anywhere in
1981 the process. Let's suppose here that the main procedure is named
1982 ``ada_main`` and that in the DLL there is an entry point named
1983 ``ada_dll``.
1984
1985 The DLL (:ref:`Introduction_to_Dynamic_Link_Libraries_DLLs`) and
1986 program must have been built with the debugging information (see GNAT -g
1987 switch). Here are the step-by-step instructions for debugging it:
1988
1989 * Launch ``GDB`` on the main program.
1990
1991 ::
1992
1993 $ gdb -nw ada_main
1994
1995 * Start the program and stop at the beginning of the main procedure
1996
1997 ::
1998
1999 (gdb) start
2000
2001 This step is required to be able to set a breakpoint inside the DLL. As long
2002 as the program is not run, the DLL is not loaded. This has the
2003 consequence that the DLL debugging information is also not loaded, so it is not
2004 possible to set a breakpoint in the DLL.
2005
2006 * Set a breakpoint inside the DLL
2007
2008 ::
2009
2010 (gdb) break ada_dll
2011 (gdb) cont
2012
2013 At this stage a breakpoint is set inside the DLL. From there on
2014 you can use the standard approach to debug the whole program
2015 (:ref:`Running_and_Debugging_Ada_Programs`).
2016
2017
2018 .. _Program_Built_with_Foreign_Tools_and_DLL_Built_with_GCC/GNAT:
2019
2020 Program Built with Foreign Tools and DLL Built with GCC/GNAT
2021 """"""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2022
2023 In this case things are slightly more complex because it is not possible to
2024 start the main program and then break at the beginning to load the DLL and the
2025 associated DLL debugging information. It is not possible to break at the
2026 beginning of the program because there is no ``GDB`` debugging information,
2027 and therefore there is no direct way of getting initial control. This
2028 section addresses this issue by describing some methods that can be used
2029 to break somewhere in the DLL to debug it.
2030
2031 First suppose that the main procedure is named ``main`` (this is for
2032 example some C code built with Microsoft Visual C) and that there is a
2033 DLL named ``test.dll`` containing an Ada entry point named
2034 ``ada_dll``.
2035
2036 The DLL (see :ref:`Introduction_to_Dynamic_Link_Libraries_DLLs`) must have
2037 been built with debugging information (see the GNAT :switch:`-g` option).
2038
2039
2040 .. rubric:: Debugging the DLL Directly
2041
2042 * Find out the executable starting address
2043
2044 ::
2045
2046 $ objdump --file-header main.exe
2047
2048 The starting address is reported on the last line. For example:
2049
2050 ::
2051
2052 main.exe: file format pei-i386
2053 architecture: i386, flags 0x0000010a:
2054 EXEC_P, HAS_DEBUG, D_PAGED
2055 start address 0x00401010
2056
2057 * Launch the debugger on the executable.
2058
2059 ::
2060
2061 $ gdb main.exe
2062
2063 * Set a breakpoint at the starting address, and launch the program.
2064
2065 ::
2066
2067 $ (gdb) break *0x00401010
2068 $ (gdb) run
2069
2070 The program will stop at the given address.
2071
2072 * Set a breakpoint on a DLL subroutine.
2073
2074 ::
2075
2076 (gdb) break ada_dll.adb:45
2077
2078 Or if you want to break using a symbol on the DLL, you need first to
2079 select the Ada language (language used by the DLL).
2080
2081 ::
2082
2083 (gdb) set language ada
2084 (gdb) break ada_dll
2085
2086 * Continue the program.
2087
2088 ::
2089
2090 (gdb) cont
2091
2092 This will run the program until it reaches the breakpoint that has been
2093 set. From that point you can use the standard way to debug a program
2094 as described in (:ref:`Running_and_Debugging_Ada_Programs`).
2095
2096 It is also possible to debug the DLL by attaching to a running process.
2097
2098
2099 .. rubric:: Attaching to a Running Process
2100
2101 .. index:: DLL debugging, attach to process
2102
2103 With ``GDB`` it is always possible to debug a running process by
2104 attaching to it. It is possible to debug a DLL this way. The limitation
2105 of this approach is that the DLL must run long enough to perform the
2106 attach operation. It may be useful for instance to insert a time wasting
2107 loop in the code of the DLL to meet this criterion.
2108
2109 * Launch the main program :file:`main.exe`.
2110
2111 ::
2112
2113 $ main
2114
2115 * Use the Windows *Task Manager* to find the process ID. Let's say
2116 that the process PID for :file:`main.exe` is 208.
2117
2118 * Launch gdb.
2119
2120 ::
2121
2122 $ gdb
2123
2124 * Attach to the running process to be debugged.
2125
2126 ::
2127
2128 (gdb) attach 208
2129
2130 * Load the process debugging information.
2131
2132 ::
2133
2134 (gdb) symbol-file main.exe
2135
2136 * Break somewhere in the DLL.
2137
2138 ::
2139
2140 (gdb) break ada_dll
2141
2142 * Continue process execution.
2143
2144 ::
2145
2146 (gdb) cont
2147
2148 This last step will resume the process execution, and stop at
2149 the breakpoint we have set. From there you can use the standard
2150 approach to debug a program as described in
2151 :ref:`Running_and_Debugging_Ada_Programs`.
2152
2153
2154 .. _Setting_Stack_Size_from_gnatlink:
2155
2156 Setting Stack Size from ``gnatlink``
2157 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
2158
2159 It is possible to specify the program stack size at link time. On modern
2160 versions of Windows, starting with XP, this is mostly useful to set the size of
2161 the main stack (environment task). The other task stacks are set with pragma
2162 Storage_Size or with the *gnatbind -d* command.
2163
2164 Since older versions of Windows (2000, NT4, etc.) do not allow setting the
2165 reserve size of individual tasks, the link-time stack size applies to all
2166 tasks, and pragma Storage_Size has no effect.
2167 In particular, Stack Overflow checks are made against this
2168 link-time specified size.
2169
2170 This setting can be done with ``gnatlink`` using either of the following:
2171
2172
2173 * :switch:`-Xlinker` linker option
2174
2175 ::
2176
2177 $ gnatlink hello -Xlinker --stack=0x10000,0x1000
2178
2179
2180 This sets the stack reserve size to 0x10000 bytes and the stack commit
2181 size to 0x1000 bytes.
2182
2183 * :switch:`-Wl` linker option
2184
2185 ::
2186
2187 $ gnatlink hello -Wl,--stack=0x1000000
2188
2189 This sets the stack reserve size to 0x1000000 bytes. Note that with
2190 :switch:`-Wl` option it is not possible to set the stack commit size
2191 because the comma is a separator for this option.
2192
2193
2194 .. _Setting_Heap_Size_from_gnatlink:
2195
2196 Setting Heap Size from ``gnatlink``
2197 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
2198
2199 Under Windows systems, it is possible to specify the program heap size from
2200 ``gnatlink`` using either of the following:
2201
2202 * :switch:`-Xlinker` linker option
2203
2204 ::
2205
2206 $ gnatlink hello -Xlinker --heap=0x10000,0x1000
2207
2208 This sets the heap reserve size to 0x10000 bytes and the heap commit
2209 size to 0x1000 bytes.
2210
2211 * :switch:`-Wl` linker option
2212
2213 ::
2214
2215 $ gnatlink hello -Wl,--heap=0x1000000
2216
2217
2218 This sets the heap reserve size to 0x1000000 bytes. Note that with
2219 :switch:`-Wl` option it is not possible to set the heap commit size
2220 because the comma is a separator for this option.
2221
2222
2223 .. _Win32_Specific_Addons:
2224
2225 Windows Specific Add-Ons
2226 -------------------------
2227
2228 This section describes the Windows specific add-ons.
2229
2230 .. _Win32Ada:
2231
2232 Win32Ada
2233 ^^^^^^^^
2234
2235 Win32Ada is a binding for the Microsoft Win32 API. This binding can be
2236 easily installed from the provided installer. To use the Win32Ada
2237 binding you need to use a project file, and adding a single with_clause
2238 will give you full access to the Win32Ada binding sources and ensure
2239 that the proper libraries are passed to the linker.
2240
2241 .. code-block:: gpr
2242
2243 with "win32ada";
2244 project P is
2245 for Sources use ...;
2246 end P;
2247
2248 To build the application you just need to call gprbuild for the
2249 application's project, here p.gpr:
2250
2251 .. code-block:: sh
2252
2253 gprbuild p.gpr
2254
2255 .. _wPOSIX:
2256
2257 wPOSIX
2258 ^^^^^^
2259
2260 wPOSIX is a minimal POSIX binding whose goal is to help with building
2261 cross-platforms applications. This binding is not complete though, as
2262 the Win32 API does not provide the necessary support for all POSIX APIs.
2263
2264 To use the wPOSIX binding you need to use a project file, and adding
2265 a single with_clause will give you full access to the wPOSIX binding
2266 sources and ensure that the proper libraries are passed to the linker.
2267
2268 .. code-block:: gpr
2269
2270 with "wposix";
2271 project P is
2272 for Sources use ...;
2273 end P;
2274
2275 To build the application you just need to call gprbuild for the
2276 application's project, here p.gpr:
2277
2278 .. code-block:: sh
2279
2280 gprbuild p.gpr
2281
2282
2283 .. _Mac_OS_Topics:
2284
2285 Mac OS Topics
2286 =============
2287
2288 .. index:: OS X
2289
2290 This section describes topics that are specific to Apple's OS X
2291 platform.
2292
2293 Codesigning the Debugger
2294 ------------------------
2295
2296 The Darwin Kernel requires the debugger to have special permissions
2297 before it is allowed to control other processes. These permissions
2298 are granted by codesigning the GDB executable. Without these
2299 permissions, the debugger will report error messages such as::
2300
2301 Starting program: /x/y/foo
2302 Unable to find Mach task port for process-id 28885: (os/kern) failure (0x5).
2303 (please check gdb is codesigned - see taskgated(8))
2304
2305 Codesigning requires a certificate. The following procedure explains
2306 how to create one:
2307
2308 * Start the Keychain Access application (in
2309 /Applications/Utilities/Keychain Access.app)
2310
2311 * Select the Keychain Access -> Certificate Assistant ->
2312 Create a Certificate... menu
2313
2314 * Then:
2315
2316 * Choose a name for the new certificate (this procedure will use
2317 "gdb-cert" as an example)
2318
2319 * Set "Identity Type" to "Self Signed Root"
2320
2321 * Set "Certificate Type" to "Code Signing"
2322
2323 * Activate the "Let me override defaults" option
2324
2325
2326 * Click several times on "Continue" until the "Specify a Location
2327 For The Certificate" screen appears, then set "Keychain" to "System"
2328
2329 * Click on "Continue" until the certificate is created
2330
2331 * Finally, in the view, double-click on the new certificate,
2332 and set "When using this certificate" to "Always Trust"
2333
2334 * Exit the Keychain Access application and restart the computer
2335 (this is unfortunately required)
2336
2337
2338 Once a certificate has been created, the debugger can be codesigned
2339 as follow. In a Terminal, run the following command:
2340
2341 ::
2342
2343 $ codesign -f -s "gdb-cert" <gnat_install_prefix>/bin/gdb
2344
2345 where "gdb-cert" should be replaced by the actual certificate
2346 name chosen above, and <gnat_install_prefix> should be replaced by
2347 the location where you installed GNAT. Also, be sure that users are
2348 in the Unix group ``_developer``.