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