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