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 The machine configuration defaults to S5L8900X for arm and default for i386 and ppc. 19 20 This will also create a bootable image, mach_kernel, and a kernel binary 21 with symbols, mach_kernel.sys. 22 23 Examples: 24 /* make a debug kernel for H1 arm board */ 25 make TARGET_CONFIGS="debug arm s5l8900x" 26 27 $(OBJROOT)/DEBUG_ARM_S5L8900X/osfmk/DEBUG/osfmk.o: pre-linked object for osfmk component 28 $(OBJROOT)/DEBUG_ARM_S5L8900X/mach_kernel: bootable image 29 30 /* make debug and development kernels for H1 arm board */ 31 make TARGET_CONFIGS="debug arm s5l8900x development arm s5l8900x" 32 33 $(OBJROOT)/DEBUG_ARM_S5L8900X/osfmk/DEBUG/osfmk.o: pre-linked object for osfmk component 34 $(OBJROOT)/DEBUG_ARM_S5L8900X/mach_kernel: bootable image 35 $(OBJROOT)/DEVELOPMENT_ARM_S5L8900X/osfmk/DEVELOPMENT/osfmk.o: pre-linked object for osfmk component 36 $(OBJROOT)/DEVELOPMENT_ARM_S5L8900X/mach_kernel: bootable image 37 38 /* this is all you need to do to build H1 arm with DEVELOPMENT kernel configuration */ 39 make TARGET_CONFIGS="default arm default" 40 41 or the following is equivalent 42 43 make ARCH_CONFIGS=ARM 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_PPC/osfmk/RELEASE/osfmk.o: pre-linked object for 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 PPC DEFAULT" all 85 86 or 87 88 $ make KERNEL_CONFIGS=DEBUG all 89 90 or 91 92 $ export TARGET_CONFIGS="DEBUG ARM MX31ADS" 93 $ make all 94 95 Example: 96 $(OBJROOT)/DEBUG_PPC/osfmk/DEBUG/osfmk.o: pre-linked object for osfmk component 97 $(OBJROOT)/DEBUG_PPC/mach_kernel: bootable image 98 994) Building fat 100 101 Define architectures in your environment or when running a make command. 102 Apply procedures 3, 4, 5 103 104 $ make TARGET_CONFIGS="RELEASE PPC default RELEASE I386 default" exporthdrs all 105 106 or 107 108 $ make ARCH_CONFIGS="PPC I386" exporthdrs all 109 110 or 111 112 $ export ARCH_CONFIGS="PPC I386" 113 $ make exporthdrs all 114 1155) Verbose make 116 To display complete tool invocations rather than an abbreviated version, 117 $ make VERBOSE=YES 118 1196) Debug information formats 120 By default, a DWARF debug information repository is created during the install phase; this is a "bundle" named mach_kernel.dSYM 121 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. 122 $ export BUILD_STABS=1 123 $ make 124 1257) Build check before integration 126 127 From the top directory, run: 128 129 $ ~rc/bin/buildit . -arch ppc -arch i386 -noinstallsrc -nosum 130 131 or for multiple arm builds 132 133 $ ~rc/bin/buildit . -noinstallsrc -nosum -- TARGET_CONFIGS="release arm MX31ADS release arm LN2410SBC" 134 135 or for default arm build (kernel config DEVELOPMENT and machine config MX31ADS) 136 137 $ ~rc/bin/buildit . -arch arm -noinstallsrc -nosum -- TARGET_CONFIGS="release arm MX31ADS release arm LN2410SBC" 138 139 1408) Creating tags and cscope 141 142 Set up your build environment as per instructions in 2a 143 144 From the top directory, run: 145 146 $ make tags # this will build ctags and etags on a case-sensitive 147 # volume, only ctags on case-insensitive 148 149 $ make TAGS # this will build etags 150 151 $ make cscope # this will build cscope database 152 153============================================= 154B. How to install a new header file from XNU 155 156[Note: This does not covers installing header file in IOKit framework] 157 1581) XNU installs header files at the following locations - 159 a. $(DSTROOT)/System/Library/Frameworks/Kernel.framework/Headers 160 b. $(DSTROOT)/System/Library/Frameworks/Kernel.framework/PrivateHeaders 161 c. $(DSTROOT)/System/Library/Frameworks/System.framework/Headers 162 d. $(DSTROOT)/System/Library/Frameworks/System.framework/PrivateHeaders 163 e. $(DSTROOT)/usr/include/ 164 165 Kernel.framework is used by kernel extensions. System.framework 166 and /usr/include are used by user level applications. The header 167 files in framework's "PrivateHeaders" are only available for Apple 168 Internal development. 169 1702) The directory containing the header file should have a Makefile that 171 creates the list of files that should be installed at different locations. 172 If you are adding first header file in a directory, you will need to 173 create Makefile similar to xnu/bsd/sys/Makefile. 174 175 Add your header file to the correct file list depending on where you want 176 to install it. The default locations where the header files are installed 177 from each file list are - 178 179 a. DATAFILES : To make header file available in user level - 180 $(DSTROOT)/System/Library/Frameworks/System.framework/Headers 181 $(DSTROOT)/System/Library/Frameworks/System.framework/PrivateHeaders 182 $(DSTROOT)/usr/include/ 183 184 b. PRIVATE_DATAFILES : To make header file available to Apple internal in 185 user level - 186 $(DSTROOT)/System/Library/Frameworks/System.framework/PrivateHeaders 187 188 c. KERNELFILES : To make header file available in kernel level - 189 $(DSTROOT)/System/Library/Frameworks/Kernel.framework/Headers 190 $(DSTROOT)/System/Library/Frameworks/Kernel.framework/PrivateHeaders 191 192 d. PRIVATE_KERNELFILES : To make header file available to Apple internal 193 for kernel extensions - 194 $(DSTROOT)/System/Library/Frameworks/Kernel.framework/PrivateHeaders 195 1963) The Makefile combines the file lists mentioned above into different 197 install lists which are used by build system to install the header files. 198 199 If the install list that you are interested does not exists, create it 200 by adding the appropriate file lists. The default install lists, its 201 member file lists and their default location are described below - 202 203 a. INSTALL_MI_LIST : Installs header file to location that is available to 204 everyone in user level. 205 Locations - 206 $(DSTROOT)/System/Library/Frameworks/System.framework/Headers 207 $(DSTROOT)/usr/include/ 208 Definition - 209 INSTALL_MI_LIST = ${DATAFILES} 210 211 b. INSTALL_MI_LCL_LIST : Installs header file to location that is available 212 for Apple internal in user level. 213 Locations - 214 $(DSTROOT)/System/Library/Frameworks/System.framework/PrivateHeaders 215 Definition - 216 INSTALL_MI_LCL_LIST = ${DATAFILES} ${PRIVATE_DATAFILES} 217 218 c. INSTALL_KF_MI_LIST : Installs header file to location that is available 219 to everyone for kernel extensions. 220 Locations - 221 $(DSTROOT)/System/Library/Frameworks/Kernel.framework/Headers 222 Definition - 223 INSTALL_KF_MI_LIST = ${KERNELFILES} 224 225 d. INSTALL_KF_MI_LCL_LIST : Installs header file to location that is 226 available for Apple internal for kernel extensions. 227 Locations - 228 $(DSTROOT)/System/Library/Frameworks/Kernel.framework/PrivateHeaders 229 Definition - 230 INSTALL_KF_MI_LCL_LIST = ${KERNELFILES} ${PRIVATE_KERNELFILES} 231 2324) If you want to install the header file in a sub-directory of the paths 233 described in (1), specify the directory name using two variable 234 INSTALL_MI_DIR and EXPORT_MI_DIR as follows - 235 236 INSTALL_MI_DIR = dirname 237 EXPORT_MI_DIR = dirname 238 2395) A single header file can exist at different locations using the steps 240 mentioned above. However it might not be desirable to make all the code 241 in the header file available at all the locations. For example, you 242 want to export a function only to kernel level but not user level. 243 244 You can use C language's pre-processor directive (#ifdef, #endif, #ifndef) 245 to control the text generated before a header file is installed. The kernel 246 only includes the code if the conditional macro is TRUE and strips out 247 code for FALSE conditions from the header file. 248 249 Some pre-defined macros and their descriptions are - 250 a. PRIVATE : If true, code is available to all of the xnu kernel and is 251 not available in kernel extensions and user level header files. The 252 header files installed in all the paths described above in (1) will not 253 have code enclosed within this macro. 254 255 b. KERNEL_PRIVATE : Same as PRIVATE 256 257 c. BSD_KERNEL_PRIVATE : If true, code is available to the xnu/bsd part of 258 the kernel and is not available to rest of the kernel, kernel extensions 259 and user level header files. The header files installed in all the 260 paths described above in (1) will not have code enclosed within this 261 macro. 262 263 d. KERNEL : If true, code is available only in kernel and kernel 264 extensions and is not available in user level header files. Only the 265 header files installed in following paths will have the code - 266 $(DSTROOT)/System/Library/Frameworks/Kernel.framework/Headers 267 $(DSTROOT)/System/Library/Frameworks/Kernel.framework/PrivateHeaders 268