1Table of contents: 2A. How to build XNU 3B. How to install a new header file from XNU 4 5============================================= 6A. How to build XNU: 7 81) Type: "make" 9 10 This builds all the components for kernel, architecture, and machine 11 configurations defined in TARGET_CONFIGS. Additionally, we also support 12 architectures defined in ARCH_CONFIGS and kernel configurations defined in 13 KERNEL_CONFIGS. Note that TARGET_CONFIGS overrides any configurations defined 14 in ARCH_CONFIGS and KERNEL_CONFIGS. 15 16 By default, architecture defaults to the build machine 17 architecture, and the kernel configuration is set to build for DEVELOPMENT. 18 19 This will also create a bootable image, mach_kernel, and a kernel binary 20 with symbols, mach_kernel.sys. 21 22 23 /* this is all you need to do to build with RELEASE kernel configuration */ 24 make TARGET_CONFIGS="release x86_64 default" SDKROOT=/path/to/SDK 25 26 or the following is equivalent (ommitted SDKROOT will use /) 27 28 make ARCH_CONFIGS=X86_64 29 302) Building DEBUG 31 32 Define kernel configuration to DEBUG in your environment or when running a 33 make command. Then, apply procedures 4, 5 34 35 $ make TARGET_CONFIGS="DEBUG X86_64 DEFAULT" all 36 37 or 38 39 $ make KERNEL_CONFIGS=DEBUG ARCH_CONFIGS=X86_64 all 40 41 or 42 43 $ export TARGET_CONFIGS="DEBUG X86_64 DEFAULT" 44 $ export SDKROOT=/path/to/SDK 45 $ make all 46 47 Example: 48 $(OBJROOT)/DEBUG_X86_64/osfmk/DEBUG/osfmk.filelist: list of objects in osfmk component 49 $(OBJROOT)/DEBUG_X86_64/mach_kernel: bootable image 50 513) Building fat 52 53 Define architectures in your environment or when running a make command. 54 Apply procedures 3, 4, 5 55 56 $ make TARGET_CONFIGS="RELEASE I386 DEFAULT RELEASE X86_64 DEFAULT" exporthdrs all 57 58 or 59 60 $ make ARCH_CONFIGS="I386 X86_64" exporthdrs all 61 62 or 63 64 $ export ARCH_CONFIGS="I386 X86_64" 65 $ make exporthdrs all 66 674) Verbose make 68 To display complete tool invocations rather than an abbreviated version, 69 $ make VERBOSE=YES 70 715) Debug information formats 72 By default, a DWARF debug information repository is created during the install phase; this is a "bundle" named mach_kernel.dSYM 73 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. 74 $ export BUILD_STABS=1 75 $ make 76 776) Build check before integration 78 79 From the top directory, run: 80 81 $ ~rc/bin/buildit . -arch i386 -arch x86_64 -arch armv7 -arch ppc -noinstallsrc -nosum 82 83 84 xnu supports a number of XBS build aliases, which allow B&I to build 85 the same source submission multiple times in different ways, to 86 produce different results. Each build alias supports the standard 87 "clean", "install", "installsrc", "installhdrs" targets, but 88 conditionalize their behavior on the RC_ProjectName make variable 89 which is passed as the -project argument to ~rc/bin/buildit, which 90 can be one of: 91 92 -project xnu # the default, builds /mach_kernel, kernel-space 93 # headers, user-space headers, man pages, 94 # symbol-set kexts 95 96 -project xnu_debug # a DEBUG kernel in /AppleInternal with dSYM 97 98 -project libkxld # user-space version of kernel linker 99 100 -project libkmod # static library automatically linked into kexts 101 102 -project Libsyscall # automatically generate BSD syscall stubs 103 104 -project xnu_quick_test # install xnu unit tests 105 106 107 1087) Creating tags and cscope 109 110 Set up your build environment as per instructions in 2a 111 112 From the top directory, run: 113 114 $ make tags # this will build ctags and etags on a case-sensitive 115 # volume, only ctags on case-insensitive 116 117 $ make TAGS # this will build etags 118 119 $ make cscope # this will build cscope database 120 1218) Other makefile options 122 123 $ make MAKEJOBS=-j8 # this will use 8 processes during the build. The default is 2x the number of active CPUS. 124 $ make -j8 # the standard command-line option is also accepted 125 126 $ make -w # trace recursive make invocations. Useful in combination with VERBOSE=YES 127 128 $ make BUILD_LTO=1 # build with LLVM Link Time Optimization (experimental) 129 130 $ make REMOTEBUILD=user@remotehost # perform build on remote host 131 132============================================= 133B. How to install a new header file from XNU 134 135[Note: This does not cover installing header files in IOKit framework] 136 1371) XNU installs header files at the following locations - 138 a. $(DSTROOT)/System/Library/Frameworks/Kernel.framework/Headers 139 b. $(DSTROOT)/System/Library/Frameworks/Kernel.framework/PrivateHeaders 140 c. $(DSTROOT)/System/Library/Frameworks/System.framework/Headers 141 d. $(DSTROOT)/System/Library/Frameworks/System.framework/PrivateHeaders 142 e. $(DSTROOT)/usr/include/ 143 144 Kernel.framework is used by kernel extensions. System.framework 145 and /usr/include are used by user level applications. The header 146 files in framework's "PrivateHeaders" are only available for Apple 147 Internal development. 148 1492) The directory containing the header file should have a Makefile that 150 creates the list of files that should be installed at different locations. 151 If you are adding first header file in a directory, you will need to 152 create Makefile similar to xnu/bsd/sys/Makefile. 153 154 Add your header file to the correct file list depending on where you want 155 to install it. The default locations where the header files are installed 156 from each file list are - 157 158 a. DATAFILES : To make header file available in user level - 159 $(DSTROOT)/System/Library/Frameworks/System.framework/Headers 160 $(DSTROOT)/System/Library/Frameworks/System.framework/PrivateHeaders 161 $(DSTROOT)/usr/include/ 162 163 b. PRIVATE_DATAFILES : To make header file available to Apple internal in 164 user level - 165 $(DSTROOT)/System/Library/Frameworks/System.framework/PrivateHeaders 166 167 c. KERNELFILES : To make header file available in kernel level - 168 $(DSTROOT)/System/Library/Frameworks/Kernel.framework/Headers 169 $(DSTROOT)/System/Library/Frameworks/Kernel.framework/PrivateHeaders 170 171 d. PRIVATE_KERNELFILES : To make header file available to Apple internal 172 for kernel extensions - 173 $(DSTROOT)/System/Library/Frameworks/Kernel.framework/PrivateHeaders 174 1753) The Makefile combines the file lists mentioned above into different 176 install lists which are used by build system to install the header files. 177 178 If the install list that you are interested does not exist, create it 179 by adding the appropriate file lists. The default install lists, its 180 member file lists and their default location are described below - 181 182 a. INSTALL_MI_LIST : Installs header file to location that is available to 183 everyone in user level. 184 Locations - 185 $(DSTROOT)/System/Library/Frameworks/System.framework/Headers 186 $(DSTROOT)/usr/include/ 187 Definition - 188 INSTALL_MI_LIST = ${DATAFILES} 189 190 b. INSTALL_MI_LCL_LIST : Installs header file to location that is available 191 for Apple internal in user level. 192 Locations - 193 $(DSTROOT)/System/Library/Frameworks/System.framework/PrivateHeaders 194 Definition - 195 INSTALL_MI_LCL_LIST = ${DATAFILES} ${PRIVATE_DATAFILES} 196 197 c. INSTALL_KF_MI_LIST : Installs header file to location that is available 198 to everyone for kernel extensions. 199 Locations - 200 $(DSTROOT)/System/Library/Frameworks/Kernel.framework/Headers 201 Definition - 202 INSTALL_KF_MI_LIST = ${KERNELFILES} 203 204 d. INSTALL_KF_MI_LCL_LIST : Installs header file to location that is 205 available for Apple internal for kernel extensions. 206 Locations - 207 $(DSTROOT)/System/Library/Frameworks/Kernel.framework/PrivateHeaders 208 Definition - 209 INSTALL_KF_MI_LCL_LIST = ${KERNELFILES} ${PRIVATE_KERNELFILES} 210 2114) If you want to install the header file in a sub-directory of the paths 212 described in (1), specify the directory name using two variable 213 INSTALL_MI_DIR and EXPORT_MI_DIR as follows - 214 215 INSTALL_MI_DIR = dirname 216 EXPORT_MI_DIR = dirname 217 2185) A single header file can exist at different locations using the steps 219 mentioned above. However it might not be desirable to make all the code 220 in the header file available at all the locations. For example, you 221 want to export a function only to kernel level but not user level. 222 223 You can use C language's pre-processor directive (#ifdef, #endif, #ifndef) 224 to control the text generated before a header file is installed. The kernel 225 only includes the code if the conditional macro is TRUE and strips out 226 code for FALSE conditions from the header file. 227 228 Some pre-defined macros and their descriptions are - 229 a. PRIVATE : If true, code is available to all of the xnu kernel and is 230 not available in kernel extensions and user level header files. The 231 header files installed in all the paths described above in (1) will not 232 have code enclosed within this macro. 233 234 b. KERNEL_PRIVATE : Same as PRIVATE 235 236 c. BSD_KERNEL_PRIVATE : If true, code is available to the xnu/bsd part of 237 the kernel and is not available to rest of the kernel, kernel extensions 238 and user level header files. The header files installed in all the 239 paths described above in (1) will not have code enclosed within this 240 macro. 241 242 d. KERNEL : If true, code is available only in kernel and kernel 243 extensions and is not available in user level header files. Only the 244 header files installed in following paths will have the code - 245 $(DSTROOT)/System/Library/Frameworks/Kernel.framework/Headers 246 $(DSTROOT)/System/Library/Frameworks/Kernel.framework/PrivateHeaders 247