-How to build XNU:
+Table of contents:
+A. How to build XNU
+B. How to install a new header file from XNU
+
+=============================================
+A. How to build XNU:
1) Type: "make"
- This builds all the components for all architectures defined in
- ARCH_CONFIGS and for all kernel configurations defined in KERNEL_CONFIGS.
- By default, ARCH_CONFIGS contains one architecture, the build machine
- architecture, and KERNEL_CONFIGS is set to build for RELEASE.
+ This builds all the components for kernel, architecture, and machine
+ configurations defined in TARGET_CONFIGS. Additionally, we also support
+ architectures defined in ARCH_CONFIGS and kernel configurations defined in
+ KERNEL_CONFIGS. Note that TARGET_CONFIGS overrides any configurations defined
+ in ARCH_CONFIGS and KERNEL_CONFIGS.
+
+ By default, architecture defaults to the build machine
+ architecture, and the kernel configuration is set to build for DEVELOPMENT.
+
This will also create a bootable image, mach_kernel, and a kernel binary
with symbols, mach_kernel.sys.
- Example:
- $(OBJROOT)/RELEASE_PPC/osfmk/RELEASE/osfmk.o: pre-linked object for osfmk component
- $(OBJROOT)/RELEASE_PPC/mach_kernel: bootable image
-2) Building a Component
+ /* this is all you need to do to build with RELEASE kernel configuration */
+ make TARGET_CONFIGS="release x86_64 default" SDKROOT=/path/to/SDK
+
+ or the following is equivalent (ommitted SDKROOT will use /)
+
+ make ARCH_CONFIGS=X86_64
- Go to the top directory in your XNU project.
+2) Building DEBUG
- If you are using a sh-style shell, run the following command:
- $ . SETUP/setup.sh
+ Define kernel configuration to DEBUG in your environment or when running a
+ make command. Then, apply procedures 4, 5
- If you are using a csh-style shell, run the following command:
- % source SETUP/setup.csh
+ $ make TARGET_CONFIGS="DEBUG X86_64 DEFAULT" all
- This will define the following environmental variables:
- SRCROOT, OBJROOT, DSTROOT, SYMROOT
+ or
- From a component top directory:
+ $ make KERNEL_CONFIGS=DEBUG ARCH_CONFIGS=X86_64 all
- $ make all
+ or
- This builds a component for all architectures defined in ARCH_CONFIGS
- and for all kernel configurations defined in KERNEL_CONFIGS.
- By default, ARCH_CONFIGS contains one architecture, the build machine
- architecture, and KERNEL_CONFIGS is set to build for RELEASE .
+ $ export TARGET_CONFIGS="DEBUG X86_64 DEFAULT"
+ $ export SDKROOT=/path/to/SDK
+ $ make all
Example:
- $(OBJROOT)/RELEASE_PPC/osfmk/RELEASE/osfmk.o: pre-linked object for osfmk component
+ $(OBJROOT)/DEBUG_X86_64/osfmk/DEBUG/osfmk.filelist: list of objects in osfmk component
+ $(OBJROOT)/DEBUG_X86_64/mach_kernel: bootable image
- From the component top directory:
+3) Building fat
- $ make mach_kernel
+ Define architectures in your environment or when running a make command.
+ Apply procedures 3, 4, 5
- This includes your component in the bootable image, mach_kernel, and
- in the kernel binary with symbols, mach_kernel.sys.
+ $ make TARGET_CONFIGS="RELEASE I386 DEFAULT RELEASE X86_64 DEFAULT" exporthdrs all
- WARNING: If a component header file has been modified, you will have to do
- the above procedure 1.
+ or
-3) Building DEBUG
+ $ make ARCH_CONFIGS="I386 X86_64" exporthdrs all
- Define KERNEL_CONFIGS to DEBUG in your environment or when running a
- make command. Then, apply procedures 4, 5
+ or
- $ make KERNEL_CONFIGS=DEBUG all
+ $ export ARCH_CONFIGS="I386 X86_64"
+ $ make exporthdrs all
- or
+4) Verbose make
+ To display complete tool invocations rather than an abbreviated version,
+ $ make VERBOSE=YES
- $ export KERNEL_CONFIGS=DEBUG
- $ make all
+5) Debug information formats
+ By default, a DWARF debug information repository is created during the install phase; this is a "bundle" named mach_kernel.dSYM
+ 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.
+ $ export BUILD_STABS=1
+ $ make
- Example:
- $(OBJROOT)/DEBUG_PPC/osfmk/DEBUG/osfmk.o: pre-linked object for osfmk component
- $(OBJROOT)/DEBUG_PPC/mach_kernel: bootable image
+6) Build check before integration
-4) Building fat
+ From the top directory, run:
- Define ARCH_CONFIGS in your environment or when running a make command.
- Apply procedures 3, 4, 5
+ $ ~rc/bin/buildit . -arch i386 -arch x86_64 -arch armv7 -arch ppc -noinstallsrc -nosum
- $ make ARCH_CONFIGS="PPC I386" exporthdrs all
+
+ xnu supports a number of XBS build aliases, which allow B&I to build
+ the same source submission multiple times in different ways, to
+ produce different results. Each build alias supports the standard
+ "clean", "install", "installsrc", "installhdrs" targets, but
+ conditionalize their behavior on the RC_ProjectName make variable
+ which is passed as the -project argument to ~rc/bin/buildit, which
+ can be one of:
- or
+ -project xnu # the default, builds /mach_kernel, kernel-space
+ # headers, user-space headers, man pages,
+ # symbol-set kexts
- $ export ARCH_CONFIGS="PPC I386"
- $ make exporthdrs all
+ -project xnu_debug # a DEBUG kernel in /AppleInternal with dSYM
-5) Build check before integration
+ -project libkxld # user-space version of kernel linker
- From the top directory, run:
+ -project libkmod # static library automatically linked into kexts
+
+ -project Libsyscall # automatically generate BSD syscall stubs
+
+ -project xnu_quick_test # install xnu unit tests
- $ ~rc/bin/buildit . -arch ppc -arch i386 -noinstallsrc -nosum
-6) Creating tags and cscope
+
+7) Creating tags and cscope
Set up your build environment as per instructions in 2a
From the top directory, run:
- $ make tags # this will build ctags and etags
+ $ make tags # this will build ctags and etags on a case-sensitive
+ # volume, only ctags on case-insensitive
+
+ $ make TAGS # this will build etags
$ make cscope # this will build cscope database
+8) Other makefile options
+
+ $ make MAKEJOBS=-j8 # this will use 8 processes during the build. The default is 2x the number of active CPUS.
+ $ make -j8 # the standard command-line option is also accepted
+
+ $ make -w # trace recursive make invocations. Useful in combination with VERBOSE=YES
+
+ $ make BUILD_LTO=1 # build with LLVM Link Time Optimization (experimental)
+
+ $ make REMOTEBUILD=user@remotehost # perform build on remote host
+
+=============================================
+B. How to install a new header file from XNU
+
+[Note: This does not cover installing header files in IOKit framework]
+
+1) XNU installs header files at the following locations -
+ a. $(DSTROOT)/System/Library/Frameworks/Kernel.framework/Headers
+ b. $(DSTROOT)/System/Library/Frameworks/Kernel.framework/PrivateHeaders
+ c. $(DSTROOT)/System/Library/Frameworks/System.framework/Headers
+ d. $(DSTROOT)/System/Library/Frameworks/System.framework/PrivateHeaders
+ e. $(DSTROOT)/usr/include/
+
+ Kernel.framework is used by kernel extensions. System.framework
+ and /usr/include are used by user level applications. The header
+ files in framework's "PrivateHeaders" are only available for Apple
+ Internal development.
+
+2) The directory containing the header file should have a Makefile that
+ creates the list of files that should be installed at different locations.
+ If you are adding first header file in a directory, you will need to
+ create Makefile similar to xnu/bsd/sys/Makefile.
+
+ Add your header file to the correct file list depending on where you want
+ to install it. The default locations where the header files are installed
+ from each file list are -
+
+ a. DATAFILES : To make header file available in user level -
+ $(DSTROOT)/System/Library/Frameworks/System.framework/Headers
+ $(DSTROOT)/System/Library/Frameworks/System.framework/PrivateHeaders
+ $(DSTROOT)/usr/include/
+
+ b. PRIVATE_DATAFILES : To make header file available to Apple internal in
+ user level -
+ $(DSTROOT)/System/Library/Frameworks/System.framework/PrivateHeaders
+
+ c. KERNELFILES : To make header file available in kernel level -
+ $(DSTROOT)/System/Library/Frameworks/Kernel.framework/Headers
+ $(DSTROOT)/System/Library/Frameworks/Kernel.framework/PrivateHeaders
+
+ d. PRIVATE_KERNELFILES : To make header file available to Apple internal
+ for kernel extensions -
+ $(DSTROOT)/System/Library/Frameworks/Kernel.framework/PrivateHeaders
+
+3) The Makefile combines the file lists mentioned above into different
+ install lists which are used by build system to install the header files.
+
+ If the install list that you are interested does not exist, create it
+ by adding the appropriate file lists. The default install lists, its
+ member file lists and their default location are described below -
+
+ a. INSTALL_MI_LIST : Installs header file to location that is available to
+ everyone in user level.
+ Locations -
+ $(DSTROOT)/System/Library/Frameworks/System.framework/Headers
+ $(DSTROOT)/usr/include/
+ Definition -
+ INSTALL_MI_LIST = ${DATAFILES}
+
+ b. INSTALL_MI_LCL_LIST : Installs header file to location that is available
+ for Apple internal in user level.
+ Locations -
+ $(DSTROOT)/System/Library/Frameworks/System.framework/PrivateHeaders
+ Definition -
+ INSTALL_MI_LCL_LIST = ${DATAFILES} ${PRIVATE_DATAFILES}
+
+ c. INSTALL_KF_MI_LIST : Installs header file to location that is available
+ to everyone for kernel extensions.
+ Locations -
+ $(DSTROOT)/System/Library/Frameworks/Kernel.framework/Headers
+ Definition -
+ INSTALL_KF_MI_LIST = ${KERNELFILES}
+
+ d. INSTALL_KF_MI_LCL_LIST : Installs header file to location that is
+ available for Apple internal for kernel extensions.
+ Locations -
+ $(DSTROOT)/System/Library/Frameworks/Kernel.framework/PrivateHeaders
+ Definition -
+ INSTALL_KF_MI_LCL_LIST = ${KERNELFILES} ${PRIVATE_KERNELFILES}
+
+4) If you want to install the header file in a sub-directory of the paths
+ described in (1), specify the directory name using two variable
+ INSTALL_MI_DIR and EXPORT_MI_DIR as follows -
+
+ INSTALL_MI_DIR = dirname
+ EXPORT_MI_DIR = dirname
+
+5) A single header file can exist at different locations using the steps
+ mentioned above. However it might not be desirable to make all the code
+ in the header file available at all the locations. For example, you
+ want to export a function only to kernel level but not user level.
+
+ You can use C language's pre-processor directive (#ifdef, #endif, #ifndef)
+ to control the text generated before a header file is installed. The kernel
+ only includes the code if the conditional macro is TRUE and strips out
+ code for FALSE conditions from the header file.
+
+ Some pre-defined macros and their descriptions are -
+ a. PRIVATE : If true, code is available to all of the xnu kernel and is
+ not available in kernel extensions and user level header files. The
+ header files installed in all the paths described above in (1) will not
+ have code enclosed within this macro.
+
+ b. KERNEL_PRIVATE : Same as PRIVATE
+
+ c. BSD_KERNEL_PRIVATE : If true, code is available to the xnu/bsd part of
+ the kernel and is not available to rest of the kernel, kernel extensions
+ and user level header files. The header files installed in all the
+ paths described above in (1) will not have code enclosed within this
+ macro.
+
+ d. KERNEL : If true, code is available only in kernel and kernel
+ extensions and is not available in user level header files. Only the
+ header files installed in following paths will have the code -
+ $(DSTROOT)/System/Library/Frameworks/Kernel.framework/Headers
+ $(DSTROOT)/System/Library/Frameworks/Kernel.framework/PrivateHeaders
projects / apple / xnu.git / blobdiff