1Table of contents:
2A. How to build XNU
3B. How to install a new header file from XNU
4C. Building XNU on a Linux x32/x64 host.
5D. Installing XNU headers on a Linux x32/x64 host.
6E. Installing libkmod/libkmodc++ on a Linux x32/x64 host.
7
8(I am putting this up online as I no longer will have time to personally
9 maintain this project.)
10
11=============================================
12A. How to build XNU:
13
141) Type: "make"
15
16 This builds all the components for kernel, architecture, and machine
17 configurations defined in TARGET_CONFIGS. Additionally, we also support
18 architectures defined in ARCH_CONFIGS and kernel configurations defined in
19 KERNEL_CONFIGS. Note that TARGET_CONFIGS overrides any configurations defined
20 in ARCH_CONFIGS and KERNEL_CONFIGS.
21
22 By default, architecture defaults to the build machine
23 architecture, and the kernel configuration is set to build for DEVELOPMENT.
24 The machine configuration defaults to ARMPBA8 for arm and nothing for i386 and x86_64.
25
26 This will also create a bootable image, mach_kernel, and a kernel binary
27 with symbols, mach_kernel.sys.
28
29 Alternatively, you can edit "machine_configuration" to set the default targets to build
30 if you are using the xnu-build script.
31
32 Here are the valid arm machine configs:
33 OMAP3530 OMAP3430_RX51 OMAP335X ARMPBA8 S5L8930X S5L8920X S5L8922X
34
35 Here are the valid armv6 machine configs: (YOU WILL *NEED* TO USE Xcode 4.4.1 or similar.)
36 S5L8720X S5L8900XRB ARM_RVEB_V6
37
38 Examples:
39 /* make a debug kernel for OMAP3530 arm board */
40 make TARGET_CONFIGS="debug arm OMAP3530"
41
42 $(OBJROOT)/DEBUG_ARM_OMAP3530/osfmk/DEBUG/osfmk.o: pre-linked object for osfmk component
43 $(OBJROOT)/DEBUG_ARM_OMAP3530/mach_kernel: bootable image
44
452) Building a Component
46
47 Go to the top directory in your XNU project.
48
49 If you are using a sh-style shell, run the following command:
50 $ . SETUP/setup.sh
51
52 If you are using a csh-style shell, run the following command:
53 % source SETUP/setup.csh
54
55 This will define the following environmental variables:
56 SRCROOT, OBJROOT, DSTROOT, SYMROOT
57
58 From a component top directory:
59
60 $ make all
61
62 This builds a component for all architectures, kernel configurations, and
63 machine configurations defined in TARGET_CONFIGS (or alternately ARCH_CONFIGS
64 and KERNEL_CONFIGS).
65
66 Example:
67 $(OBJROOT)/RELEASE_X86_64/osfmk/RELEASE/osfmk.filelist: list of objects in osfmk component
68
69 From the component top directory:
70
71 $ make mach_kernel
72
73 This includes your component in the bootable image, mach_kernel, and
74 in the kernel binary with symbols, mach_kernel.sys.
75
76 WARNING: If a component header file has been modified, you will have to do
77 the above procedure 1.
78
793) Building DEBUG
80
81 Define kernel configuration to DEBUG in your environment or when running a
82 make command. Then, apply procedures 4, 5
83
84 $ make TARGET_CONFIGS="DEBUG X86_64 DEFAULT" all
85
86 or
87
88 $ make KERNEL_CONFIGS=DEBUG ARCH_CONFIGS=X86_64 all
89
90 or
91
92 $ export TARGET_CONFIGS="DEBUG X86_64 DEFAULT"
93 $ export SDKROOT=/path/to/SDK
94 $ make all
95
96 Example:
97 $(OBJROOT)/DEBUG_X86_64/osfmk/DEBUG/osfmk.filelist: list of objects in osfmk component
98 $(OBJROOT)/DEBUG_X86_64/mach_kernel: bootable image
99
1004) Building fat
101
102 Define architectures in your environment or when running a make command.
103 Apply procedures 3, 4, 5
104
105 $ make TARGET_CONFIGS="RELEASE I386 DEFAULT RELEASE X86_64 DEFAULT" exporthdrs all
106
107 or
108
109 $ make ARCH_CONFIGS="I386 X86_64" exporthdrs all
110
111 or
112
113 $ export ARCH_CONFIGS="I386 X86_64"
114 $ make exporthdrs all
115
1165) Verbose make
117 To display complete tool invocations rather than an abbreviated version,
118 $ make VERBOSE=YES
119
1206) Debug information formats
121 By default, a DWARF debug information repository is created during the install phase; this is a "bundle" named mach_kernel.dSYM
122 To select the older STABS debug information format (where debug information is embedded in the mach_kernel.sys image), set the BUILD_STABS environment variable.
123 $ export BUILD_STABS=1
124 $ make
125
1267) Build check before integration
127
128 From the top directory, run:
129
130 $ ~rc/bin/buildit . -arch i386 -arch x86_64 -arch armv7 -arch ppc -noinstallsrc -nosum
131
132
133 xnu supports a number of XBS build aliases, which allow B&I to build
134 the same source submission multiple times in different ways, to
135 produce different results. Each build alias supports the standard
136 "clean", "install", "installsrc", "installhdrs" targets, but
137 conditionalize their behavior on the RC_ProjectName make variable
138 which is passed as the -project argument to ~rc/bin/buildit, which
139 can be one of:
140
141 -project xnu # the default, builds /mach_kernel, kernel-space
142 # headers, user-space headers, man pages,
143 # symbol-set kexts
144
145 -project xnu_debug # a DEBUG kernel in /AppleInternal with dSYM
146
147 -project libkxld # user-space version of kernel linker
148
149 -project libkmod # static library automatically linked into kexts
150
151 -project Libsyscall # automatically generate BSD syscall stubs
152
153
154
1558) Creating tags and cscope
156
157 Set up your build environment as per instructions in 2a
158
159 From the top directory, run:
160
161 $ make tags # this will build ctags and etags on a case-sensitive
162 # volume, only ctags on case-insensitive
163
164 $ make TAGS # this will build etags
165
166 $ make cscope # this will build cscope database
167
1689) Other makefile options
169
170 $ make MAKEJOBS=-j8 # this will use 8 processes during the build. The default is 2x the number of active cores
171
172 $ make -w # trace recursive make invocations. Useful in combination with VERBOSE=YES
173
174 $ make BUILD_LTO=1 # build with LLVM Link Time Optimization (experimental)
175
176 $ make BUILD_INTEGRATED_ASSEMBLER=1 # build with LLVM integrated assembler (experimental)
177
178=============================================
179B. How to install a new header file from XNU
180
181[Note: This does not cover installing header files in IOKit framework]
182
1831) XNU installs header files at the following locations -
184 a. $(DSTROOT)/System/Library/Frameworks/Kernel.framework/Headers
185 b. $(DSTROOT)/System/Library/Frameworks/Kernel.framework/PrivateHeaders
186 c. $(DSTROOT)/System/Library/Frameworks/System.framework/Headers
187 d. $(DSTROOT)/System/Library/Frameworks/System.framework/PrivateHeaders
188 e. $(DSTROOT)/usr/include/
189
190 Kernel.framework is used by kernel extensions. System.framework
191 and /usr/include are used by user level applications. The header
192 files in framework's "PrivateHeaders" are only available for Apple
193 Internal development.
194
1952) The directory containing the header file should have a Makefile that
196 creates the list of files that should be installed at different locations.
197 If you are adding first header file in a directory, you will need to
198 create Makefile similar to xnu/bsd/sys/Makefile.
199
200 Add your header file to the correct file list depending on where you want
201 to install it. The default locations where the header files are installed
202 from each file list are -
203
204 a. DATAFILES : To make header file available in user level -
205 $(DSTROOT)/System/Library/Frameworks/System.framework/Headers
206 $(DSTROOT)/System/Library/Frameworks/System.framework/PrivateHeaders
207 $(DSTROOT)/usr/include/
208
209 b. PRIVATE_DATAFILES : To make header file available to Apple internal in
210 user level -
211 $(DSTROOT)/System/Library/Frameworks/System.framework/PrivateHeaders
212
213 c. KERNELFILES : To make header file available in kernel level -
214 $(DSTROOT)/System/Library/Frameworks/Kernel.framework/Headers
215 $(DSTROOT)/System/Library/Frameworks/Kernel.framework/PrivateHeaders
216
217 d. PRIVATE_KERNELFILES : To make header file available to Apple internal
218 for kernel extensions -
219 $(DSTROOT)/System/Library/Frameworks/Kernel.framework/PrivateHeaders
220
2213) The Makefile combines the file lists mentioned above into different
222 install lists which are used by build system to install the header files.
223
224 If the install list that you are interested does not exist, create it
225 by adding the appropriate file lists. The default install lists, its
226 member file lists and their default location are described below -
227
228 a. INSTALL_MI_LIST : Installs header file to location that is available to
229 everyone in user level.
230 Locations -
231 $(DSTROOT)/System/Library/Frameworks/System.framework/Headers
232 $(DSTROOT)/usr/include/
233 Definition -
234 INSTALL_MI_LIST = ${DATAFILES}
235
236 b. INSTALL_MI_LCL_LIST : Installs header file to location that is available
237 for Apple internal in user level.
238 Locations -
239 $(DSTROOT)/System/Library/Frameworks/System.framework/PrivateHeaders
240 Definition -
241 INSTALL_MI_LCL_LIST = ${DATAFILES} ${PRIVATE_DATAFILES}
242
243 c. INSTALL_KF_MI_LIST : Installs header file to location that is available
244 to everyone for kernel extensions.
245 Locations -
246 $(DSTROOT)/System/Library/Frameworks/Kernel.framework/Headers
247 Definition -
248 INSTALL_KF_MI_LIST = ${KERNELFILES}
249
250 d. INSTALL_KF_MI_LCL_LIST : Installs header file to location that is
251 available for Apple internal for kernel extensions.
252 Locations -
253 $(DSTROOT)/System/Library/Frameworks/Kernel.framework/PrivateHeaders
254 Definition -
255 INSTALL_KF_MI_LCL_LIST = ${KERNELFILES} ${PRIVATE_KERNELFILES}
256
2574) If you want to install the header file in a sub-directory of the paths
258 described in (1), specify the directory name using two variable
259 INSTALL_MI_DIR and EXPORT_MI_DIR as follows -
260
261 INSTALL_MI_DIR = dirname
262 EXPORT_MI_DIR = dirname
263
2645) A single header file can exist at different locations using the steps
265 mentioned above. However it might not be desirable to make all the code
266 in the header file available at all the locations. For example, you
267 want to export a function only to kernel level but not user level.
268
269 You can use C language's pre-processor directive (#ifdef, #endif, #ifndef)
270 to control the text generated before a header file is installed. The kernel
271 only includes the code if the conditional macro is TRUE and strips out
272 code for FALSE conditions from the header file.
273
274 Some pre-defined macros and their descriptions are -
275 a. PRIVATE : If true, code is available to all of the xnu kernel and is
276 not available in kernel extensions and user level header files. The
277 header files installed in all the paths described above in (1) will not
278 have code enclosed within this macro.
279
280 b. KERNEL_PRIVATE : Same as PRIVATE
281
282 c. BSD_KERNEL_PRIVATE : If true, code is available to the xnu/bsd part of
283 the kernel and is not available to rest of the kernel, kernel extensions
284 and user level header files. The header files installed in all the
285 paths described above in (1) will not have code enclosed within this
286 macro.
287
288 d. KERNEL : If true, code is available only in kernel and kernel
289 extensions and is not available in user level header files. Only the
290 header files installed in following paths will have the code -
291 $(DSTROOT)/System/Library/Frameworks/Kernel.framework/Headers
292 $(DSTROOT)/System/Library/Frameworks/Kernel.framework/PrivateHeaders
293
294=============================================
295C. Building XNU on a Linux x32/x64 Host.
296[Note: Everything beyond this point assumes that you have xnu-deps-linux installed]
297
2981) Type the following into your command line:
299
300 make TARGET_CONFIGS="debug arm armpba8"
301
302 More work needs to be done on this. (Fixing dtrace stuff such as ctfconvert, etc)
303
304=============================================
305D. Installing XNU headers on a Linux x32/x64 Host.
306
3071) Type the following into your command line:
308
309 make TARGET_CONFIGS="debug arm armpba8" DSTROOT="${HOME}/KernelSDK" installhdrs
310
311==============================================
312E. Installing libkmod/libkmodc++ on a Linux x32/x64 Host.
313
3141) Type the following into your command line:
315
316 make TARGET_CONFIGS="debug arm armpba8" RC_ProjectName=libkmod DSTROOT="${HOME}/KernelSDK"
317