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
|
DRuntime: Runtime Library for the D Programming Language
========================================================
This is a collection of things that people hacking on
DRuntime will want to know.
Code style
----------
Please follow the D style guide when writing code for
DRuntime: http://dlang.org/dstyle.html
The D style guide doesn't cover everything so when in
doubt, use the code style already used in the module you
are modifying, or whatever style you prefer if you're
adding a new module.
Publicity of modules
--------------------
In general, only modules in the 'core' package should be
made public. The single exception is the 'object' module
which is not in any package.
The convention is to put private modules in the 'rt' or
'gc' packages depending on what they do and only put
public modules in 'core'.
Also, always avoid importing private modules in public
modules. If a public module consists of a header file
and an implementation file (which are both maintained by
hand) then it is OK to import private modules in the
implementation file.
Adding new modules
------------------
When adding a new module, remember to update all three
makefiles as necessary:
* posix.mak
* win32.mak
* win64.mak
A number of shared utility makefiles also need to be
updated:
* mak/COPY
* mak/DOCS
* mak/IMPORTS
* mak/MANIFEST
* mak/SRCS
Operating system bindings
-------------------------
The 'core.sys' package provides bindings to most APIs
provided by supported operating systems.
The convention is to have OS-specific stuff in a
'core.sys.os' package where 'os' is the canonical name
for the OS (e.g. 'linux', 'osx', 'windows').
There is also the 'core.sys.posix' package in which
bindings to standardized POSIX APIs should be placed.
In this package, the convention is to put declarations
in sections based on the OS being compiled for. See
src/core/sys/posix/pwd.d for an example of how these
modules are arranged.
For all OS headers, it's a good idea to put a version
attribute at the top of the file containing the OS
the header is intended for. For example, in POSIX
modules, this would be 'version (Posix):' while in
Windows modules it would be 'version (Windows):' and
so on.
The convention is to have a D module per C header.
C99 bindings
------------
The 'core.stdc' package provides bindings to all C99
library types, functions, and macros. Unlike the style
in operating system bindings, bindings here should be
kept system-agnostic whenever possible.
Deprecation process
-------------------
Never remove a symbol without going through the proper
deprecation process.
When, for whatever reason, a symbol is to be deprecated,
annotate it as such using the 'deprecated' attribute. It
is a good idea to also provide a message on the attribute
so that the user can immediately see what symbol they
should use instead.
After six months of having been deprecated, a symbol can
be removed completely. It may also be kept around for
backwards compatibility if deemed necessary.
ABI breakage
------------
We're trying to get to a point where DRuntime's ABI is
completely stable and different compiler versions can
use different DRuntime versions. To this end, avoid
making ABI-breaking changes unless you have a *very*
good reason to do it.
Remember that renaming a symbol and leaving an alias
behind for the old symbol name *is* an ABI break. The
compiled name will be the new symbol, thus breaking old
binaries.
Updating the change log
-----------------------
It's a good idea to not update the change log in a pull
request. It tends to create merge conflicts between
pull requests more often than not.
That said, an occasional pull request to update the
change log with recent changes (i.e. in a batch) is OK.
|
