-
Notifications
You must be signed in to change notification settings - Fork 5
/
Copy pathfd2pragma.guide
2200 lines (1800 loc) · 92 KB
/
fd2pragma.guide
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
@database fd2pragma.guide
@$VER: fd2pragma.guide 1.64 (21.01.2004)
@index Index
@node Main "fd2pragma - the programmers file generator"
fd2pragma - the programmers file generator
@{"About the program" LINK About} What this program is able to do
@{"About this documentation" LINK Docs} Read this!
@{"Beginner" LINK Beginner} Easy start for beginners
@{"Options" LINK Options} What options may be used to control it
@{"Useful example calls" LINK Examples} Most useful calls
@{"The important options" LINK OptionAll} Main options for everyone
@{"The advanced options" LINK OptionAdvanced} Options for more detailed control
@{"About includes" LINK Includes} What C includes are useful and required
Some words about
@{"Default names" LINK Names} The default output file names
@{"Link libraries" LINK LinkLib} Generated link library files
@{"Proto files" LINK Proto} Generated proto files
@{"Include definitions" LINK IncludeDefs} Overview of supported definitions
@{"Local library base files" LINK Local} C includes for local library base support
@{"Header scan" LINK HeaderScan} The way the HEADER option works
@{"Tag-functions" LINK TagFuncs} The way tag-functions are found
@{"fd2pragma.types" LINK TypesFile} The fd2pragma.types definition file
@{"FPU usage" LINK FPUusage} Functions using FPU registers
@{"PowerUP" LINK PowerUP} Phase 5 PowerUP files
@{"VBCC" LINK VBCC} VBCC compiler files
@{"Important words" LINK Words} Explanation of words and phrases used
@{"Bugs and Problems" LINK Bugs} Known bugs and problems
@{"Library design" LINK LibDesign} Short words on how to design your own libraries
@{"Pragma design" LINK PragmaDesign} Design description of pragmas
@{"XML file design" LINK XMLDesign} Design description of XML-IDL files
@{"SFD file design" LINK SFDDesign} Design description of SFD files
@{"FD file design" LINK FDDesign} Design description of FD files
@{"Register usage" LINK Registers} Usage of 680x0 registers
@{"Scripts" LINK Scripts} Useful scripts to generate needed files
@{"usefd2pragma" LINK usefd2pragma} Useful script interface
@{"The End - Last words" LINK Last} Greetings, author's address ,...
@{"Index" LINK Index} Index of important phrases
Calling the program seems to be (is) very difficult, but it offers you a
large set of functions. A lot of options need a lot of abilities to turn
them on/off! The program has an internal help, which can be accessed by the
standard method: First call "fd2pragma ?" to get the synopsis and afterwards
enter ? again to get the argument description. Nobody can remember all the
SPECIAL options without that!
Read this documentation very carefully, because there are some notes you
may not see on fast reading, but which will help you a lot. (for example
HEADER option and "" filename)
@endnode
@remark ********************************************************************
@node About
This is a utility to create:
- the following pragma statements for certain C compilers: amicall,
libcall, flibcall, tagcall, and syscall
- proto files for C compilers
- offset (LVO) files for assembler programs
- stub functions for either tag-functions or all library functions
- stub functions as assembler text
- stub functions as usable link library file
- FD files out of pragma files
- stubs for C++ compilers (SPECIAL 11, 12, and CLIB)
- the files with your own headers inserted
- files for using local pointers for shared library bases in compilers
which do not normally support this
- stub functions for Pascal compilers
- inline files for GCC
- inline, pragma, and stub libraries using FPU registers
- files needed to develop for Phase5's PowerUP boards
- unit texts for FPC Pascal compiler
- BMAP files for AmigaBASIC and MaxonBASIC
- VBCC assembler inline files
- VBCC WOS stub texts and link library
- VBCC PowerUP stub texts and link library
- VBCC MorphOS stub texts and link library
- Modules for AmigaE
- FD files
- CLIB files
- SFD files
- auto library open files for VBCC
- MorphOS files
- OS4 XML files
- OS4 cross-call code stubs
Therefor only the FD file giving the library information is needed. For
some SPECIAL options you may additionally supply the CLIB keyword (or you
need to supply it) giving fd2pragma the prototypes file in clib directory.
Better is to supply the all-in-one SFD format as input.
Special option 200 does the opposite of the usual: it converts pragma to FD!
Please tell me if something is missing. I do not know all the possibilities
of different compiler systems that I do not have, so maybe I disabled some
stuff (e.g. entries for PPC), which could be produced normally.
Commodore had a special program called sfd, which created FD files, pragmas,
stub libs, clib includes, and fd files out of a special sfd file format.
Because this format was never released to the public we need to use a
program like fd2pragma which uses FD and clib files as input. It is able to
create all needed files as well. As fd2pragma is a lot newer than the
Commodore tool it can do some more stuff (inline files, Storm files, VBCC
files, GCC files, link libraries, C++ names). I got finally the rights to
include and release the SFD format, so fd2pragma now also supports this
definition files. Thanks a lot to Olaf Barthel for making this possible.
I suggest using SFD instead of FD in the future, as it is much better
usable and covers all required information in one file. And it means your
files are equal to the system development files. OS4 introduces yet another
new format, which reduces the SFD format to the parts relevant for OS4 and
which uses a standard XML container. fd2pragma does not yet support this
format as input source.
@endnode
@remark ********************************************************************
@node Docs
This documentation is a collection of nearly all the necessary information
about development files related to library creation.
It describes the program fd2pragma, its options, the resulting files, the
source files, and all the data formats. It also covers a lot of tips and
suggestions for designing your own libraries and for designing the
development material.
If something is missing or unclear, contact me and I will fix the stuff.
Greetings go to Gary Goldberg for reading the whole document and fixing lots
of errors.
@endnode
@remark ********************************************************************
@node Beginner
To make using fd2pragma much easier I collected some example calls, which
maybe useful when suing fd2pragma seldom.
All the example are based on dos.library files. Replace intuition with
the library you want to create files for. Also use the directories which
are used on you system.
If you have the newer SFD files installed, replace all
"fd/dos_lib.fd CLIB clib/dos_protos.h" with "sfd/dos_lib.sfd".
If these examples do not fit your needs try different numbers for SPECIAL
or start using the additional options.
*******************
Users of MaxonC++ or StormC++ up to Version V3:
1) Create the correct pragma files:
fd2pragma fd/dos_lib.fd CLIB clib/dos_protos.h TO pragma SPECIAL 6
2) Create the correct proto files:
fd2pragma fd/dos_lib.fd CLIB clib/dos_protos.h TO proto SPECIAL 35
*******************
Users of SAS-C
1) Create the correct pragma files:
fd2pragma fd/dos_lib.fd CLIB clib/dos_protos.h TO pragma SPECIAL 6
2) Create the correct proto files:
fd2pragma fd/dos_lib.fd CLIB clib/dos_protos.h TO proto SPECIAL 35
*******************
Users of Storm V4
1) Create the correct inline files:
fd2pragma fd/dos_lib.fd CLIB clib/dos_protos.h TO inline SPECIAL 43
2) Create the correct proto files:
fd2pragma fd/dos_lib.fd CLIB clib/dos_protos.h TO proto SPECIAL 39
*******************
Users of GCC
1) Create the correct inline files:
fd2pragma fd/dos_lib.fd CLIB clib/dos_protos.h TO inline SPECIAL 40
2) Create the correct proto files:
fd2pragma fd/dos_lib.fd CLIB clib/dos_protos.h TO proto SPECIAL 35
*******************
Users of VBCC (when using inlines)
1) Create the correct inline files:
fd2pragma fd/dos_lib.fd CLIB clib/dos_protos.h TO inline SPECIAL 70
2) Create the correct proto files:
fd2pragma fd/dos_lib.fd CLIB clib/dos_protos.h TO proto SPECIAL 38
*******************
All systems
1) Create pragmas to proto redirect:
fd2pragma fd/dos_lib.fd CLIB clib/dos_protos.h TO pragmas SPECIAL 80
@endnode
@remark ********************************************************************
@node Options
You get the command template with fd2pragma ? .
FROM=INFILE/A,SPECIAL/N,MODE/N,TO/K,ABI/K,CLIB/K,COPYRIGHT/K,HEADER/K,
HUNKNAME/K,BASENAME/K,LIBTYPE/K,LIBNAME/K,PRIORITY/N/K,PREFIX/K,
SUBPREFIX/K,PREMACRO/K,COMMENT/S,EXTERNC/S,FPUONLY/S,NEWSYNTAX/S,NOFPU/S,
NOPPC/S,NOPPCREGNAME/S,NOSYMBOL/S,ONLYCNAMES/S,OPT040/S,PPCONLY/S,
PRIVATE/S,SECTION/S,SMALLCODE/S,SMALLDATA/S,SORTED/S,SYSTEMRELEASE/S,
USESYSCALL/S,VOIDBASE/S:
In this position you may press <?> again and you get the following text!
Remember that! I myself need this whenever I call the program, as nobody
can remember all these options.
Be careful, because this text is longer than one normal high-resolution
screen, so it is useful to press a key in the middle of the text to stop
the output.
INFILE: the input file which should be used
SPECIAL:
*OBSOL* 1 - Aztec compiler (xxx_lib.h, MODE 2, AMICALL)
*OBSOL* 2 - DICE compiler (xxx_pragmas.h, MODE 3, LIBCALL)
*OBSOL* 3 - SAS compiler (xxx_pragmas.h, MODE 3, LIBCALL,LIBTAGS)
*OBSOL* 4 - MAXON compiler (xxx_lib.h, MODE 1, AMICALL)
*OBSOL* 5 - STORM compiler (xxx_lib.h, MODE 1, AMITAGS,AMICALL)
6 - pragma for all compilers [default]
*OBSOL* 7 - all compilers with pragma to inline redirect for GCC
10 - stub-functions for C - C text
*OBSOL* 11 - stub-functions for C - assembler text
12 - stub-functions for C - link library
13 - defines and link library for local library base (register call)
14 - defines and link library for local library base (stack call)
*OBSOL* 15 - stub-functions for Pascal - assembler text
16 - stub-functions for Pascal - link library
17 - BMAP file for AmigaBASIC and MaxonBASIC
18 - module for AmigaE
20 - assembler lvo _lvo.i file
21 - assembler lvo _lib.i file
22 - assembler lvo _lvo.i file no XDEF
23 - assembler lvo _lib.i file no XDEF
24 - assembler lvo link library
*OBSOL* 30 - proto file with pragma/..._lib.h call
*OBSOL* 31 - proto file with pragma/..._pragmas.h call
*OBSOL* 32 - proto file with pragmas/..._lib.h call
*OBSOL* 33 - proto file with pragmas/..._pragmas.h call
*OBSOL* 34 - proto file with local/..._loc.h call
35 - proto file for all compilers (VBCC stubs)
*OBSOL* 36 - proto file for GNU-C compiler only
*OBSOL* 37 - proto file without lib definitions
38 - proto file for all compilers (VBCC inline)
*OBSOL* 39 - proto file with special PPC related checks
40 - GCC inline file (preprocessor based)
41 - GCC inline file (old type - inline based)
42 - GCC inline file (library stubs)
43 - GCC inline file (new style - macro)
44 - GCC inline file (new style - inline)
45 - GCC inline file (new style - inline with include lines)
46 - GCC inline file (preprocessor based, direct)
47 - GCC inline file (new style, direct)
48 - GCC inline file (preprocessor based, direct, StormGCC)
50 - GCC inline files for PowerUP (preprocessor based)
51 - GCC inline files for PowerUP (old type - inline based)
52 - GCC inline files for PowerUP (library stubs)
53 - SAS-C include file for PowerUP
54 - Proto file for PowerUP
60 - FPC pascal unit text
70 - VBCC inline files
*OBSOL* 71 - VBCC WOS stub-functions - assembler text
*OBSOL* 72 - VBCC WOS stub-functions - assembler text (libbase)
73 - VBCC WOS stub-functions - link library
74 - VBCC WOS stub-functions - link library (libbase)
*OBSOL* 75 - VBCC PowerUP stub-functions - assembler text
76 - VBCC PowerUP stub-functions - link library
77 - VBCC WOS inline files
78 - VBCC MorphOS stub-functions - link library
*OBSOL* 79 - VBCC old inline files
80 - pragma/proto redirect (xxx_pragmas.h, SAS/Dice)
81 - pragma/proto redirect (xxx_lib.h, Aztec/Maxon/Storm)
82 - pragma/proto redirect (xxx.h, GCC)
83 - pragma/proto redirect (xxx_protos.h, VBCC)
90 - stub-functions for C - assembler text (multiple files)
91 - VBCC PowerUP stub-functions - assembler text (multiple files)
92 - VBCC WOS stub-functions - assembler text (multiple files)
93 - VBCC MorphOS stub-functions - assembler text (multiple files)
100 - PPC assembler lvo file
101 - PPC assembler lvo file no XDEF
102 - PPC assembler lvo ELF link library
103 - PPC assembler lvo EHF link library
104 - PPC V.4-ABI assembler file
105 - PPC V.4-ABI assembler file no XDEF
106 - PPC V.4-ABI assembler lvo ELF link library
107 - PPC V.4-ABI assembler lvo EHF link library
110 - FD file
111 - CLIB file
112 - SFD file
120 - VBCC auto libopen files (C source)
121 - VBCC auto libopen files (m68k link library)
122 - VBCC MorphOS inline files
130 - GCC inline files for MorphOS (preprocessor based)
131 - GCC inline files for MorphOS (old type - inline based)
132 - GCC inline files for MorphOS (library stubs)
133 - GCC inline files for MorphOS (library stubs, direct varargs)
134 - MorphOS gate stubs
135 - MorphOS gate stubs (prelib)
136 - MorphOS gate stubs (postlib)
137 - MorphOS gate stubs (reglib, prelib)
138 - MorphOS gate stubs (reglib, postlib)
140 - OS4 XML file
141 - OS4 PPC->M68K cross-call stubs
142 - OS4 M68K->PPC cross-call stubs
200 - FD file (source is a pragma file!)
MODE: SPECIAL 1-7:
1: _INCLUDE_PRAGMA_..._LIB_H definition method [default]
2: _PRAGMAS_..._LIB_H definition method
3: _PRAGMAS_..._PRAGMAS_H definition method
4: no definition
SPECIAL 11-14,40-45,50-53,70-76,78,90-91,111-112,122,
130-138,141:
1: all functions, normal interface
2: only tag-functions, tagcall interface
3: all functions, normal and tagcall interface [default]
TO: the destination directory (self creation of filename)
ABI: set ABI type (m68k|ppc|ppc0|ppc2)
CLIB: name of the prototypes file in clib directory
COPYRIGHT: the copyright text for CLIB files
HEADER: inserts given file into header of created file ("" is scan)
HUNKNAME: use this name for HUNK_NAME instead of default 'text'
BASENAME: name of library base without '_'
LIBNAME: name of the library (.e.g. dos.library)
LIBTYPE: type of base library structure
PRIORITY: priority for auto open files
PREFIX: MorphOS gate prefix
SUBPREFIX: MorphOS gate sub prefix
PREMACRO: MorphOS gate file start macro
Switches:
AUTOHEADER add the typical automatic generated header
COMMENT: copy comments found in input file
EXTERNC: add a #ifdef __cplusplus ... statement to pragma file
FPUONLY: work only with functions using FPU register arguments
NEWSYNTAX: uses new Motorola syntax for asm files
NOFPU: disable usage of FPU register arguments
NOPPC: disable usage of PPC-ABI functions
NOPPCREGNAME: do not add 'r' to PPC register names
NOSYMBOL: prevents creation of SYMBOL hunks for link libraries
ONLYCNAMES: do not create C++ or ASM names
OPT040: optimize for 68040, do not use MOVEM for stubs
PPCONLY: only use PPC-ABI functions
PRIVATE: includes private declared functions
SECTION: add section statements to asm texts
SMALLCODE: generate small code link libraries or assembler text
SMALLDATA: generate small data link libraries or assembler text
SMALLTYPES: allow 8 and 16 bit types in registers
SORTED: sort generated files by name and not by bias value
SYSTEMRELEASE: special handling of comments for system includes
USESYSCALL: uses syscall pragma instead of libcall SysBase
VOIDBASE: library bases are of type void *
@endnode
@remark ********************************************************************
@node Examples
Useful examples (with intuition.library):
1) fd2pragma <FD file> TO <pragma dir>
fd2pragma FD:intuition_lib.fd TO INCLUDE:pragma/
Creates a pragma file for all C compilers and copies it to the
given directory.
2) fd2pragma <FD file> CLIB <clib file> SPECIAL 12 TO <lib dir>
fd2pragma FD:intuition_lib.fd CLIB INCLUDE:clib/intuition_protos.h
SPECIAL 12 TO LIB:
Creates a link library holding stub functions to call tag-functions
from compilers which do not support them (MaxonC++).
3) fd2pragma <FD file> CLIB <clib file> SPECIAL 13 MODE 3
fd2pragma FD:intuition_lib.fd CLIB INCLUDE:clib/intuition_protos.h
SPECIAL 13 MODE 3
Creates a link library and an include file which allow you to call
library functions with local base variables in compilers which do
not support that (MaxonC++). See @{"below" LINK Local} how to handle these files.
4) fd2pragma <FD file> SPECIAL 34 TO <proto dir>
fd2pragma FD:intuition_lib.fd SPECIAL 34 TO INCLUDE:proto/
Creates a proto file for the local library base file include, which
was created in example 3 and copies it to the given directory.
5) fd2pragma <FD file> SPECIAL 35 TO <proto dir>
fd2pragma FD:intuition_lib.fd SPECIAL 35 TO INCLUDE:proto/
Creates a proto file for all C compilers and copies it to the
given directory.
6) fd2pragma <FD file> CLIB <clib file> SPECIAL 40
fd2pragma FD:intuition_lib.fd CLIB INCLUDE:clib/intuition_protos.h
SPECIAL 40
Creates inline include for GCC. This is used by GCC instead of
pragma files for other compilers.
@endnode
@remark ********************************************************************
@node OptionAll "Option explanation of all user options"
INFILE is the always needed source file, which describes the library. This
maybe an FD file (usually together with CLIB file) or an SFD file.
SPECIAL option:
(create a pragma file)
1: Creates a pragma file for the Aztec compiler; you will see in
the brackets above what this means.
*OBSOLETE*
2: Same as 1 for DICE compiler.
*OBSOLETE*
3: Same as 1 for SAS compiler.
*OBSOLETE*
4: Same as 1 for MAXON compiler.
*OBSOLETE*
5: Same as 1 for STORM compiler.
*OBSOLETE*
6: This option creates a pragma file usable for nearly all compilers.
This is the default when no other mode is given.
7: same as 6, but redirects file to inline directory for GCC.
*OBSOLETE*
(link libraries and their assembler code)
10: Creates stub functions in correct C code which handle the varargs
feature. CLIB parameter is useful with this to get correct functions.
The only problem with these files is that there is space wasted when
not all functions are used.
11: Same as 11, but the result as plain Assembler text.
*OBSOLETE*
12: Creates STUB functions for C compilers which are unable to call a
library directly (the result is a link library, which can be used by
the C compiler directly), and accepts option CLIB to create additional
function names for C++ compilers like MaxonC++.
13: Creates two files (a link library and a C include) which allows you to
use local library base variables also in compilers, which do normally
not support them (MaxonC++). Usually time it is useful to set option
MODE to 3 or 1. This options needs CLIB keyword for correct results.
14: Same as 13, but parameters are passed on stack.
15: Same as 16, but the result as plain Assembler text.
*OBSOLETE*
16: Creates STUB functions for PCQ Pascal compilers. The tagcall function
names are ignored, as they cannot be used with Pascal. The result is
link library. The resulting code is the same as for C compilers, but
the args are taken from the stack in reverse order. (C and Pascal
normally pass arguments on stack. C passes the last argument first
(= highest position, stack is filled backwards) and first argument last
(lowest position). Pascal is the other way round. So Pascal stubs are
C stubs with the argument order reversed.
17: Creates BMAP files used by certain BASIC variants (e.g. AmigaBASIC,
MaxonBASIC).
18: Creates Module for AmigaE.
(assembler LVO files)
20: Creates lvo file for an assembler.
21: Same as 20, but with another name.
22: Same as 20, but there are no XDEF statements in the resulting file.
23: Same as 22, but with another name.
24: Creates lvo defintion file as link library (like in amiga.lib)
(proto files - no prototypes)
30,31,32,33,34: Creates proto files for the C compiler (the difference is
in the name of the called file).
*OBSOLETE*
35: Creates proto file which calls inline files for GNU-C and
pragma/xxx_lib.h for all the others. VBCC calls no files but uses
the stubs. See also SPECIAL 38.
36: Creates proto file for GNU-C. This differs from SPECIAL 35 only by
define __CONSTLIBBASEDECL__ and removed pragma and VBCC call.
*OBSOLETE*
37: Creates proto file, which only calls CLIB and defines library base.
38: Like 35, but includes <inline/xxx_protos.h> for VBCC. This is turned
off for standard mode 35. This type is useful for m68k and MorphOS
compiler variants which have inline files (See type 122 and 70).
39: Like 35, but with special PPC related checks
*OBSOLETE*
fd2pragma knows the correct library base structures for some libraries.
All the other libraries get 'struct Library' as default.
(GCC inline files)
40: Creates new style GCC inline files.
41: Creates old style GCC inline files.
42: Same as 41, but no "extern" keyword before functions.
43: New style macro based GCC definitions. Format suggested by Bernardo
Innocenti. It is still better to use types 40-42, as at the moment it
produces code which is less optimized. But this type can be used to
prevent some errors and shortcomings in types 40-42.
44: Like 43, but uses inline functions instead of macros.
45: Like 44, but also copies include lines form clib file
46: Like 40, but needs no macro include and also fixes some problems.
47: A new style of Inlines designed by Gunther Nikl. Solves some problems
but probably introduces some new.
48: The same as 46 with a special fix for StormGCC and functions with
really lots of arguments. Will be equal to SPECIAL 46 in most cases.
(Phase5 PowerUP files)
50: Creates files like 40, but for PowerUP.
51: Creates files like 41, but for PowerUP.
52: Creates files like 42, but for PowerUP.
53: Creates SAS-C include file for PowerUP (named as pragma files in
PowerUP files for no logical reason).
54: Creates a proto file for PowerUP (usable for GNU-C and SAS).
(Pascal stuff)
60: This creates a unit text file for FPC Pascal compiler.
(VBCC stuff)
70: This creates inline files for VBCC C compiler.
71: This is an assembler stub for VBCC-WOS C compiler.
*OBSOLETE*
72: Same as 71, but first argument (r3) is library base (-l of fd2libWOS).
*OBSOLETE*
73: VBCC-WOS link library in EHF format.
74: Like 73, but first argument (r3) is library base (-l of fd2libWOS).
75: This is an assembler stub for VBCC-PowerUP C compiler.
*OBSOLETE*
76: VBCC-PowerUP link library in ar format.
77: This creates inline files for VBCC C compiler WOS functions.
78: VBCC-MorphOS link library in ar format.
79: This is like type 70, but uses the old style with library base as last
argument. It does not support variable arguments functions and should
not be used at all. This is for compatibility (better fix your code).
*OBSOLETE*
(redirect files)
80: Redirects the call to proto file. Has the name of SAS or DICE pragma
file. Should be copied to pragmas.
81: Equal to 80. Has the name of Aztec, Maxon or Storm. Should be copied
to pragmas (Aztec redirect) or pragma.
82: Equal to 80. Has the name of GCC inline file. Should be copied to
inline.
83: Equal to 80. Has the name of VBCC inline file. Should be copied to
inline.
Install only redirects for files/compilers you do not have or you will
overwrite real pragmas or inlines.
(multiple files)
90: Creates STUB functions for C compilers which are unable to call a
library directly (the result are ASM source codes), and accepts
option CLIB to create additional function names for C++ compilers
like MaxonC++.
91: These are assembler stubs for VBCC-PowerUP C compiler.
92: These are assembler stubs for VBCC-WOS C compiler.
93: These are assembler stubs for VBCC-MorphOs C compiler.
(PPC assembler LVO files)
100: Creates lvo file for an PPC assembler.
101: Same as 101, but there are no XDEF statements in the resulting file.
102: Creates lvo defintion file as ELF link library.
103: Creates lvo defintion file as EHF link library.
104: Same as 20, but names without '_'.
105: Same as 21, but names without '_'.
106: Same as 22, but names without '_'.
107: Same as 23, but names without '_'.
(source file recreation)
110: Produce an FD file.
111: Produce an CLIB file.
112: Produce an SFD file.
(auto library open files for VBCC)
120: Produce 2 C code files for auto library opening. Note option
PRIORITY and LIBNAME for these types.
121: Produce 1 m68k assembler link library for auto library opening.
122: This creates inline files for VBCC C compiler MorphOS variant.
(MorphOS files)
130: Creates new style GCC inline files for MorphOS.
131: Creates old style GCC inline files for MorphOS.
132: Creates GCC library stubs for MorphOS.
133: Creates GCC library stubs for MorphOS with direct varargs.
134: Creates MorphOS gate stubs.
135: Creates MorphOS gate stubs with prefixed library base.
136: Creates MorphOS gate stubs with postfixed library base.
137: Like 135, but with register base.
138: Like 136, but with register base.
(OS4 files)
140: Create new OS4 description format @{"XML file" LINK XMLDesign}.
141: Create new stubs for OS4 PPC->M68K cross-calls.
142: Create new stubs for OS4 M68K->PPC cross-calls. May produce one
assembler and one C file.
(FD file)
200: This creates a FD file! The option INFILE has to be a pragma file
here!
@endnode
@remark ********************************************************************
@node OptionAdvanced "Options for detailed control"
MODE:
1) given with SPECIAL 1 to 7:
- Defines, which #ifdef ...\n#define ... statement is used in the pragma
file. Option 1 is default.
2) given with SPECIAL 11 to 14, 40 to 45, 50 to 53, 70 to 76, 78, 90 to 93,
111 to 112, 122, 130 to 138:
- Defines, which functions should be created. Option 3 is default.
1 - all functions are taken in normal way with normal name
2 - only tag-functions are taken with tagcall method and tag name
3 - means 1 and 2 together
TO: Here you specify the destination directory. The internal names are used,
but the file(s) will be in the given directory.
ABI: Allows to set initial ABI type for FD file to any of the supported
types "m68k, ppc, ppc0, ppc2". This is equal to ##abi statement.
CLIB: Supply name of the prototypes file in clib directory. If this option
is given together with SPECIAL 11 and 12, additional functions names
with C++ names are created. fd2pragma knows all standard parameter types
defined in exec/types.h and dos/dos.h, all structures and some more types.
All other #typedef's bring a warning. Do not use them in prototypes files!
This parameter is needed by option SPECIAL 10, 12, 13, 40 to 42 and 50 to
53. It may be required for options 71 to 74 (depending on data).
You may define unknown types using the @{"fd2pragma.types" LINK TypesFile} file.
COPYRIGHT: The copyright text, which is used for CLIB production.
HEADER: This option gives you the ability to specify a file, which should
be inserted after the normal headers and before the clib call of standard
headers (in LVO and ASM files too). If you give "" (empty string) or @ as
filename, the destination file (if already exists) will be scanned for an
existing header. This is useful for updating files. See @{"HeaderScan" LINK "HeaderScan"}
to find out how a header must be built to be recognized.
HUNKNAME: This allows to set the HUNK_NAME to any desired value. Default is
'text'.
BASENAME: This allows to overwrite the library basename. The string must be
without leading '_'.
LIBNAME: The name of the library (e.g. dos.library).
LIBTYPE: This allows to define the structure name of base library. The program
knows some types internally and uses "Library" for all the others. Specify the
type here, if it is unknown to fd2pragma.
Example: "LIBTYPE DosLibrary" for dos_lib.fd (is known by fd2pragma).
PRIORITY: Priority for types 120 and 121.
AUTOHEADER: Adds a header line
"Automatically generated header! Do not edit!" as header. This will conflict
with own headers with undefined results.
COMMENT: Comments which are in the FD file are copied to the pragma or LVO
file, when this option is given! When SORTED is given, this option is
disabled.
EXTERNC: This options adds an #ifdef __cplusplus ... statement to the
pragma file. This option is useful for C compilers running in C++ mode, but
it seems, that they do not really need this statement. Only useful with
SPECIAL option 1-7, 13, and 14.
FPUONLY: This options is the opposite to NOFPU. It forces fd2pragma to
ignore all functions not using FPU registers for passing arguments.
It is really useless to both specify FPUONLY and NOFPU.
NEWSYNTAX: Produce new Motorola syntax for ASM output.
NOFPU: This disables usage of FPU arguments. Functions using FPU arguments
are not converted with this option (as e.g. Maxon does not support amicall
with FPU args). You get a warning for every line containing FPU arguments.
It is really useless to both specify NOFPU and FPUONLY.
NOPPC: This disables use of PPC functions. These function are totally
ignored now. You get no warning.
It is really useless to both specify NOPPC and PPCONLY.
NOPPCREGNAME: If your PPC assembler does not support the "r" before register
names, use this switch and only the register number will be printed.
NOSYMBOL: Does not create symbol hunks for link libraries.
ONLYCNAMES: If CLIB keyword is supplied, but C++ names are not wanted, this
keyword prevents creation of these additional names. Also the ASM names are
no longer created
OPT040: Optimizes stub functions for 68040, by replacing MOVEM by MOVE's.
PPCONLY: This disables use of all non-PPC functions. These function are
ignored totally now. You get no warning.
It is really useless to both specify PPCONLY and NOPPC.
PREFIX: MorphOS gate function prefix.
PREMACRO: MorphOS gate function prefix macro.
PRIVATE: Also gives you the pragmas or LVO's of private functions.
Normally these functions should never be used!
SECTION: Adds sections statements to assembler texts. Only useful with
options creating stub files.
SMALLCODE: Forces function references to use (PC) relative addressing instead
of absolute addressing.
SMALLDATA: Normally the large data model references the library base as a
global variable. In the small data model the reference is relative to
register A4 instead. This option is useful for stub texts and link
libraries.
SMALLTYPES: When converting SFD files, all the 8 and 16 bit types are
converted to LONG or ULONG as does the SFD tool. This argument disables this
behaviour and takes the types, as they are.
SORTED: This option sorts generated files by name and not by bias value.
This is only for visibility and does not change the use of the files.
SUBPREFIX: MorphOS gate function subprefix.
SYSTEMRELEASE: Some special comment handling for system release include
files.
USESYSCALL: Instructs fd2pragma to use the syscall pragma instead of a
libcall SysBase. This is useful only, when using a SPECIAL option with
LIBCALL and converting exec_lib.fd. I think only SAS compiler supports
this statement.
VOIDBASE: Very seldom it may be useful to use generic type "void *" instead of
the correct base type for some file types. This keyword allows to do so.
@endnode
@remark ********************************************************************
@node Includes
Useful include system for C compilers:
After programming a long time I arranged my includes in a way that all my
C compilers are able to use the system includes in one directory.
I copied all Amiga system includes to one directory and added some files
created with fd2pragma. These are the system includes you get, for example,
on the Amiga Developer CD.
- New directory 'pragma' contains xxx_lib.h pragma files for every
library. These files were created with SPECIAL option 6.
- New directory 'proto' contains xxx.h proto files which were created with
with SPECIAL option 35.
- New directory 'inline' contains xxx.h inline files for GCC. These files
were created with SPECIAL option 40.
Directories like 'pragmas' were deleted, when they exist. Only
'clib', 'pragma', 'proto', and library-specific directories (like 'dos',
'exec', 'libraries' and 'utility') should remain.
All the others (ISO-C stuff, compiler specials) were copied to another
directory. In S:User-StartUp I use 'Assign ADD' to join the two
directories, so that the compiler may access both.
@endnode
@remark ********************************************************************
@node Names "The default output file names"
fd2pragma automatically produces the names for output files.
If the input file is called xxx_lib.fd or xxx_lib.sfd the xxx is used as
name base, else the basename of ##base statement is used. The "Base" at
the end is stripped.
List of used names:
*******************
"xxx_cstub.h" stub functions in C code
SPECIAL 10
"xx_gates.h" MorphOS gates
SPECIAL 134-138
"xxx_lib.h" C compiler pragma files
SPECIAL 1, 4 - 7, 81
"xxx_lib.i" LVO definitions for Assembler
SPECIAL 21, 23, 100-101, 104-105
"xxx_loc.h" Local library base definition file for C compilers
SPECIAL 13, 14
"xxx_lvo.i" LVO definitions for Assembler
SPECIAL 20, 22
"xxx_pragmas.h" C compiler pragma files
SPECIAL 2, 3, 8, 53, 80
"xxx_protos.h" VBCC inline files
SPECIAL 70, 79, 83, 122
"xxx_stub.s" stub functions as Assembler text (68K, PPC)
SPECIAL 11, 15, 71, 72, 75
"libxxx.a" ar object file archive (link library)
SPECIAL 76,78
"xxx.bmap" BASIC definition file for function calls
SPECIAL 17
"xxx.h" C compiler proto or inline files
SPECIAL 30 - 48, 50 - 52, 54, 82, 130-133
"xxx.lib" link library (68K, PPC)
SPECIAL 12, 16, 73, 74
"xxxlvo.o" link library lvo entries (68K, PPC)
SPECIAL 24, 103, 107
"xxxlvo.o" link library lvo entries (PowerUP)
SPECIAL 102, 106
""xxx.m" E module
SPECIAL 18
"xxx.pas" FPC unit text file
SPECIAL 60
"xxx_lib.fd" FD file
SPECIAL 110, 200
"xxx_protos.h" CLIB file
SPECIAL 111
"xxx_lib.sfd" SFD file
SPECIAL 112
"xxx.xml" XML file
SPECIAL 140
"xxx.c" C Source
SPECIAL 141
"xxx_68k.s" Assembler source for OS4 cross-calls
SPECIAL 142
"xxx_68k.c" C Source for OS4 cross-calls
SPECIAL 142
List of used single-file names:
*******************************
The xxx in these files is the funtion name.
"xxx.s" stub function as Assembler text (68K, PPC)
SPECIAL 90-93
@endnode
@remark ********************************************************************
@node LinkLib "link libraries"
About created link libraries (SPECIAL Option 12-14):
The created link libraries are relatively large compared to other link
libraries. The size of the link library has nothing to do with the size of
the resulting program you create. The code part of my link libraries is
relatively short, but fd2pragma defines a lot of texts (which are NOT copied
to the executable program created). These texts are for easier
identification and every function also gets different names:
1) the normal asm name: <name> (e.g. CopyMem)
2) the normal C name: _<name> (e.g. _CopyMem)
3) the normal C++ name: <name>_<params> (e.g. CopyMem_PvPvUj)
4) when a function parameter is STRPTR, a second C++ name is created
5) string 3 with different register spec (only func-ptr args with reg-params)
6) string 4 with different register spec (only func-ptr args with reg-params)
Forms 3-6 occur only, when you use CLIB keyword. Forms 5 and 6 should nearly
never occur! With SPECIAL options 13 and 14 the number of strings is doubled.
The different names give a lot more flexibility and only make the link library
bigger. These names are only visible to the linker program. The resulting
executable usually is a lot smaller than the link library!
If ONLYCNAMES is given the number of names is reduced to 1 (type 2).
I think the code part of the link libraries is totally optimized. I do not
know of any possible improvement to make it shorter.
If you join all the link libraries made with SPECIAL 12 and join it with
small.lib from Developer kit, you get a replacement for amiga.lib.
@endnode
@remark ********************************************************************
@node Proto "proto files"
fd2pragma is able to generate different proto files, but I suggest using
only the file generated with SPECIAL option 35.
For system libraries and some others the correct base structure is used.
Other unknown basenames get "struct Library *" as default. You may change
that in the created proto files when another structure is correct.
The proto files support following define:
__NOLIBBASE__
When this is set before calling the proto file, the declaration of the
global library base is skipped, so that can be done in source-code. This
define is also used for GCC.
The file created with SPECIAL 36 supports an additionally define:
__CONSTLIBBASEDECL__
When this is set to "const" the library base is handled as const. This may
shorten the produced code, but you need a sourcefile without this define
to initialize the base variable.
@endnode
@remark ********************************************************************
@node IncludeDefs "defines used in include files"
The first #ifdef/#define statements of created C includes:
fd2pragma has a set of different define names for different include files.
These names are internal to allow double-inclusion of one include files
without getting errors. Standard system includes use the same system.
The normal names are: (example intuition.library)
proto files: _PROTO_INTUITION_H
local library base files: _INCLUDE_PROTO_INTUITION_LOC_H
standard pragma files: _INCLUDE_PRAGMA_INTUITION_LIB_H
C stubs files: _INCLUDE_INTUITION_CSTUB_H
inline files for GCC _INLINE_INTUITION_H
PPC inline files for GCC _PPCINLINE_INTUITION_H
SAS-C PPC pragma files _PPCPRAGMA_INTUITION_H
vbcc inline files _VBCCINLINE_INTUITION_H
MorphOS gate files _GATESTUBS_INTUITION_H
clib files CLIB_INTUITION_PROTOS_H
Non-fd2pragma names are:
other includes (path_name_extension) INTUITION_INTUITION_H
These names should never be used in other files or sources! This rule is
broken for some standard system includes, but is generally true. Compiling
may be a few seconds faster when you check these names before the #include
line, but in this case the names must be standard and they are not!
Some defines allow the user to change the behaviour of the includes:
__NOLIBBASE__
This is used in proto files. See @{"Proto files" LINK Proto} for more information.
NO_INLINE_STDARG or NO_PPCINLINE_STDARG
For GCC inline files a lot of defines exist, but this seems to be the most
important. It disables the creation of varags/tagcall functions.
For other inline defines check the created inline files.
NO_OBSOLETE
This is used in SPECIAL 7 and 80-83 redirect files. If it is used, the
compiler will return an error instead of using the redirect.
<library>_BASE_NAME
Function definitions in the inline files refer to the library base variable
through the <library>_BASE_NAME symbol (e.g. INTUITION_BASE_NAME). At the
top of the inline file, this symbol is redefined to the appropriate library
base variable name (e.g., IntuitionBase), unless it has been already
defined. This way, you can make the inlines use a field of a structure as
a library base, for example.
@endnode
@remark ********************************************************************
@node Local "local library base files"
When using SPECIAL options 13 and 14 you get two files called libname_loc.h
and libname_loc.lib. The second one is a link library and should be passed
to the compiler with program settings or in makefile. The first one is a C
header file and should be used as a replacement for files in clib, pragma,
proto and pragmas directories. Always use the libname_loc.h file instead of
these files and not together with them! Do not mix them.
I suggest copying the header file into a directory called "local".
This file holds prototypes like those in the clib directory, but with
struct Library * as the first parameter and the name prefix LOC_. Together
with the prototypes there are some defines redefining the function name to
the old one and passing the library base as first parameter. These defines
allow you to use the local library bases as normal as global bases. For
tag-functions and some exceptions these defines do not work and you have
to call the LOC_ function directly and pass the library base as first
parameter.
Use need the CLIB keyword together with SPECIAL option 13 and 14.
@endnode
@remark ********************************************************************
@node HeaderScan "How the header scan works"
Giving the HEADER option lets fd2pragma insert the file (you have to give