Sign in Join
Wiki copytemporary

FPC Unicode RTL: what changed

Revision 0 to 1. Removed lines have a minus sign; added lines have a plus sign.

Title: FPC Unicode RTL

OldNewLine
1+## The issue
2+
3+The Unicode RTL is part of an effort to create a more recent Delphi compatible RTL in Free Pascal.
4+
5+Currently, 2 points make creating code that will compile in Delphi and in Free Pascal difficult.
6+
7+- In the Delphi RTL/VCL, the string keyword means WideString (or UnicodeString): an array consisting of 2-byte characters.
8+
9+
10+
11+In Free Pascal, String is still a single-byte character as it was before Delphi 2009..
12+
13+- In Delphi, units have a namespace: *System.SysUtils*, *VCL.Forms* etc.
14+
15+
16+
17+In Free Pascal, the unit names still conform to the Delphi 7 era.
18+
19+Free Pascal has backwards compatibility high in the list of priorities, so a complete switch from one to the other is not possible.
20+
21+## The solution
22+
23+2 RTLs and packages will be created from the same codebase:
24+
25+- The backwards compatible RTL (no namespaces, single-byte string)
26+- The *Unicode RTL*, which will be Delphi 2009 and upwards compatible as much as feasible.
27+
28+The default RTL will still be the Free Pascal, backwards compatible, RTL.
29+
30+### Using unicode strings
31+
32+The Free Pascal codebase for the RTL, packages and utilities is cleaned up:
33+
34+- The compiler now defines 2 basic types: *AnsiChar* (1 byte) and *UnicodeChar* (2 bytes)
35+- The system unit defines *Char* as an alias for one of the 2 types, using a define: **UNICODERTL**
36+- The code of RTL and packages has been revised so the "string" identifier has been removed where needed.
37+- In places where the code assumes an *AnsiString*, the **AnsiString** string type is used.
38+- In places where the code is agnostic of the actual string type the **String** keyword was left in place.
39+- Similarly, *Char* has been replaced by *AnsiChar*, *PChar* has been replaced by *PAnsiChar*
40+
41+If you have code that must compile in both RTLs, you can use the following conditional compilation mechanism
42+
43+ {IF SIZEOF(CHAR)=2}
44+ // Unicode string code
45+ {$ELSE}
46+ // Ansistring string code
47+ {$ENDIF}
48+
49+As of end of July 2023, this work is completed.
50+
51+Note that the compiler itself needs a single-byte rtl, compiling the compiler with the 2-byte RTL is not supported at this time.
52+
53+### Using namespaced units
54+
55+The Free Pascal codebase is enhanced with namespaced units:
56+
57+- Using the system of include files, all available units will be made so that they exist in 2 versions: one namespaced, one not namespaced.
58+
59+Basically, the namespaced unit will look like
60+
61+ unit Api.Mysql57dyn;
62+ {$DEFINE FPC_DOTTEDUNITS}
63+ {$i mysql57dyn.pp}
64+
65+as you can see, the not-namespaced unit **mysql57dyn.pp** is included, and it starts with:
66+
67+ {$IFNDEF FPC_DOTTEDUNITS}
68+ unit mysql57dyn;
69+ {$ENDIF FPC_DOTTEDUNITS}
70+
71+The occasion has been used to make the unit names more consistent. While for many units, the name has been prefixed with the namespace, for equally many units, the name has been made more consistent.
72+
73+Depending on a define *fpmake* and the *Makefiles* will compile either the one-byte RTL or the Unicode RTL, never both together.
74+
75+### What about the compiler itself?
76+
77+The compiler itself does not use unicode strings, and it does not use namespaced units. Therefore, if you wish to compile the compiler, you must still use the traditional Free Pascal RTL.
78+
79+This is also the reason why the unicode and/or namespaced RTL and packages must be compiled separately.
80+
81+## Compiling the Unicode RTL
82+
83+If you wish to use the 1-byte RTL, you don't need to do anything special: the makefiles will still by default create the backwards compatible RTL.
84+
85+The compilation of the unicode RTL rests on the use of [[FPC Subtarget Support|Subtarget support]]. This means you can only create it using a version 3.3.1 or higher of FPC.
86+
87+The first step is to create a configuration file next to the standard free pascal config file, called **fpc-unicodertl.cfg**:
88+
89+ -dUNICODERTL
90+ -Municodestrings
91+
92+When used, this configuration file does 2 things:
93+
94+1. It defines UNICODERTL. This can be used to make the difference (where needed) between the 2 rtls.
95+2. It sets the "string" type to UnicodeString.
96+
97+To compile the unicode RTL is is now sufficient to execute the following commands (replace ppcx64 with the compiler of your choice):
98+
99+ make -C rtl clean all SUB_TARGET=unicodertl PP=/path/to/fpc/3.3.1/ppcx64
100+ make -C packages clean all SUB_TARGET=unicodertl OPT=-dUSEWIDESTRING PP=/path/to/fpc/3.3.1/ppcx64
101+ make -C utils clean all SUB_TARGET=unicodertl PP=/path/to/fpc/3.3.1/ppcx64
102+
103+(the **-dUSEWIDESTRING** is needed for the compilation of the regular expressions unit)
104+
105+To install, subsequently execute
106+
107+ make -C rtl install SUB_TARGET=unicodertl PP=/path/to/fpc/3.3.1/ppcx64
108+ make -C packages install SUB_TARGET=unicodertl PP=/path/to/fpc/3.3.1/ppcx64
109+ make -C utils install SUB_TARGET=unicodertl PP=/path/to/fpc/3.3.1/ppcx64
110+
111+At this point, this will create a non-namespaced unicode rtl.
112+
113+To compile your own code with the unicode RTL, you must then of course specify the unicodertl subtarget:
114+
115+ fpc -tunicodertl yourproject.pas
116+
117+## Compiling a namespaced RTL
118+
119+To compile a namespaced URL, it is sufficient to specify the ""FPC_DOTTEDUNITS=1"" define to the makefiles:
120+
121+ make -C rtl clean all FPC_DOTTEDUNITS=1 PP=/path/to/fpc/3.3.1/ppcx64
122+ make -C packages clean all FPC_DOTTEDUNITS=1 PP=/path/to/fpc/3.3.1/ppcx64
123+ make -C utils clean all FPC_DOTTEDUNITS=1 PP=/path/to/fpc/3.3.1/ppcx64
124+
125+To install, subsequently execute
126+
127+ make -C rtl install FPC_DOTTEDUNITS=1 PP=/path/to/fpc/3.3.1/ppcx64
128+ make -C packages install FPC_DOTTEDUNITS=1 PP=/path/to/fpc/3.3.1/ppcx64
129+ make -C utils install FPC_DOTTEDUNITS=1 PP=/path/to/fpc/3.3.1/ppcx64
130+
131+## Compiling the namespaced unicode RTL
132+
133+To compile a namespaced URL, it is sufficient to combine the techniques of the above 2 sections: specify the **SUB_TARGET=unicodertl** and the **FPC_DOTTEDUNITS=1** defines when calling make:
134+
135+ make -C rtl clean all SUB_TARGET=unicodertl FPC_DOTTEDUNITS=1 PP=/path/to/fpc/3.3.1/ppcx64
136+ make -C packages clean all SUB_TARGET=unicodertl FPC_DOTTEDUNITS=1 PP=/path/to/fpc/3.3.1/ppcx64
137+ make -C utils clean all SUB_TARGET=unicodertl FPC_DOTTEDUNITS=1 PP=/path/to/fpc/3.3.1/ppcx64
138+
139+To install, subsequently execute
140+
141+ make -C rtl install SUB_TARGET=unicodertl FPC_DOTTEDUNITS=1 PP=/path/to/fpc/3.3.1/ppcx64
142+ make -C packages install SUB_TARGET=unicodertl FPC_DOTTEDUNITS=1 PP=/path/to/fpc/3.3.1/ppcx64
143+ make -C utils install SUB_TARGET=unicodertl FPC_DOTTEDUNITS=1 PP=/path/to/fpc/3.3.1/ppcx64
144+
145+---
146+*From the Free Pascal wiki, page "FPC Unicode RTL", as it stood on 2024-03-05 after a change by Michael, out of the wiki's dump of 2024-05-26. Copyright stays with the author who wrote it, according to the old wiki's [[Licensing]] page. If you have concerns about this material, [message the admin](/wiki-contact).*
147+Category: RTL

Back to history