README

   1 Table of contents:
   2 A. How to build XNU
   3 B. How to install a new header file from XNU
   4
   5 =============================================
   6 A. How to build XNU:
   7
   8 1) 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
  30 2) Building a Component
  31
  32   Go to the top directory in your XNU project.
  33
  34   If you are using a sh-style shell, run the following command:
  35      $ . SETUP/setup.sh
  36
  37   If you are using a csh-style shell, run the following command:
  38      % source SETUP/setup.csh
  39
  40   This will define the following environmental variables:
  41     SRCROOT, OBJROOT, DSTROOT, SYMROOT
  42
  43   From a component top directory:
  44
  45     $ make all
  46
  47   This builds a component for all architectures, kernel configurations, and
  48   machine configurations defined in TARGET_CONFIGS (or alternately ARCH_CONFIGS
  49   and KERNEL_CONFIGS).
  50
  51   Example:
  52     $(OBJROOT)/RELEASE_X86_64/osfmk/RELEASE/osfmk.filelist: list of objects in osfmk component
  53
  54   From the component top directory:
  55
  56     $ make mach_kernel
  57
  58   This includes your component in the bootable image, mach_kernel,  and
  59   in the kernel binary with symbols, mach_kernel.sys.
  60
  61   WARNING: If a component header file has been modified, you will have to do
  62            the above procedure 1.
  63
  64 3) Building DEBUG
  65
  66   Define kernel configuration to DEBUG in your environment or when running a
  67   make command.  Then, apply procedures 4, 5
  68
  69   $ make TARGET_CONFIGS="DEBUG X86_64 DEFAULT" all
  70
  71   or
  72
  73   $ make KERNEL_CONFIGS=DEBUG ARCH_CONFIGS=X86_64 all
  74
  75   or
  76
  77   $ export TARGET_CONFIGS="DEBUG X86_64 DEFAULT"
  78   $ export SDKROOT=/path/to/SDK
  79   $ make all
  80
  81   Example:
  82     $(OBJROOT)/DEBUG_X86_64/osfmk/DEBUG/osfmk.filelist: list of objects in osfmk component
  83     $(OBJROOT)/DEBUG_X86_64/mach_kernel: bootable image
  84
  85 4) Building fat
  86
  87   Define architectures in your environment or when running a make command.
  88   Apply procedures 3, 4, 5
  89
  90   $ make TARGET_CONFIGS="RELEASE I386 DEFAULT RELEASE X86_64 DEFAULT" exporthdrs all
  91
  92   or
  93
  94   $ make ARCH_CONFIGS="I386 X86_64" exporthdrs all
  95
  96   or
  97
  98   $ export ARCH_CONFIGS="I386 X86_64"
  99   $ make exporthdrs all
 100
 101 5) Verbose make
 102    To display complete tool invocations rather than an abbreviated version,
 103    $ make VERBOSE=YES
 104
 105 6) Debug information formats
 106    By default, a DWARF debug information repository is created during the install phase; this is a "bundle" named mach_kernel.dSYM
 107    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.
 108    $ export BUILD_STABS=1
 109    $ make
 110
 111 7) Build check before integration
 112
 113   From the top directory, run:
 114
 115     $ ~rc/bin/buildit . -arch i386 -arch x86_64 -arch armv7 -arch ppc -noinstallsrc -nosum
 116
 117
 118   xnu supports a number of XBS build aliases, which allow B&I to build
 119   the same source submission multiple times in different ways, to
 120   produce different results. Each build alias supports the standard
 121   "clean", "install", "installsrc", "installhdrs" targets, but
 122   conditionalize their behavior on the RC_ProjectName make variable
 123   which is passed as the -project argument to ~rc/bin/buildit, which
 124   can be one of:
 125
 126   -project xnu          # the default, builds /mach_kernel, kernel-space
 127                         # headers, user-space headers, man pages,
 128                         # symbol-set kexts
 129
 130   -project xnu_debug    # a DEBUG kernel in /AppleInternal with dSYM
 131
 132   -project libkxld      # user-space version of kernel linker
 133
 134   -project libkmod      # static library automatically linked into kexts
 135
 136   -project Libsyscall   # automatically generate BSD syscall stubs
 137
 138
 139
 140 8) 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 9) Other makefile options
 154
 155    $ make MAKEJOBS=-j8    # this will use 8 processes during the build. The default is 2x the number of active cores
 156
 157    $ make -w              # trace recursive make invocations. Useful in combination with VERBOSE=YES
 158
 159    $ make BUILD_LTO=1     # build with LLVM Link Time Optimization (experimental)
 160
 161    $ make BUILD_INTEGRATED_ASSEMBLER=1 # build with LLVM integrated assembler (experimental)
 162
 163 =============================================
 164 B. How to install a new header file from XNU
 165
 166 [Note: This does not cover installing header files in IOKit framework]
 167
 168 1) XNU installs header files at the following locations -
 169         a. $(DSTROOT)/System/Library/Frameworks/Kernel.framework/Headers
 170         b. $(DSTROOT)/System/Library/Frameworks/Kernel.framework/PrivateHeaders
 171         c. $(DSTROOT)/System/Library/Frameworks/System.framework/Headers
 172         d. $(DSTROOT)/System/Library/Frameworks/System.framework/PrivateHeaders
 173         e. $(DSTROOT)/usr/include/
 174
 175         Kernel.framework is used by kernel extensions.  System.framework
 176         and /usr/include are used by user level applications.  The header
 177         files in framework's "PrivateHeaders" are only available for Apple
 178         Internal development.
 179
 180 2) The directory containing the header file should have a Makefile that
 181    creates the list of files that should be installed at different locations.
 182    If you are adding first header file in a directory, you will need to
 183    create Makefile similar to xnu/bsd/sys/Makefile.
 184
 185    Add your header file to the correct file list depending on where you want
 186    to install it.   The default locations where the header files are installed
 187    from each file list are -
 188
 189    a. DATAFILES : To make header file available in user level -
 190           $(DSTROOT)/System/Library/Frameworks/System.framework/Headers
 191           $(DSTROOT)/System/Library/Frameworks/System.framework/PrivateHeaders
 192           $(DSTROOT)/usr/include/
 193
 194    b. PRIVATE_DATAFILES : To make header file available to Apple internal in
 195       user level -
 196           $(DSTROOT)/System/Library/Frameworks/System.framework/PrivateHeaders
 197
 198    c. KERNELFILES : To make header file available in kernel level -
 199           $(DSTROOT)/System/Library/Frameworks/Kernel.framework/Headers
 200           $(DSTROOT)/System/Library/Frameworks/Kernel.framework/PrivateHeaders
 201
 202    d. PRIVATE_KERNELFILES : To make header file available to Apple internal
 203       for kernel extensions -
 204           $(DSTROOT)/System/Library/Frameworks/Kernel.framework/PrivateHeaders
 205
 206 3) The Makefile combines the file lists mentioned above into different
 207    install lists which are used by build system to install the header files.
 208
 209    If the install list that you are interested does not exist, create it
 210    by adding the appropriate file lists.  The default install lists, its
 211    member file lists and their default location are described below -
 212
 213    a. INSTALL_MI_LIST : Installs header file to location that is available to
 214       everyone in user level.
 215       Locations -
 216           $(DSTROOT)/System/Library/Frameworks/System.framework/Headers
 217           $(DSTROOT)/usr/include/
 218       Definition -
 219           INSTALL_MI_LIST = ${DATAFILES}
 220
 221    b. INSTALL_MI_LCL_LIST : Installs header file to location that is available
 222       for Apple internal in user level.
 223       Locations -
 224           $(DSTROOT)/System/Library/Frameworks/System.framework/PrivateHeaders
 225       Definition -
 226           INSTALL_MI_LCL_LIST = ${DATAFILES} ${PRIVATE_DATAFILES}
 227
 228    c. INSTALL_KF_MI_LIST : Installs header file to location that is available
 229       to everyone for kernel extensions.
 230       Locations -
 231           $(DSTROOT)/System/Library/Frameworks/Kernel.framework/Headers
 232       Definition -
 233           INSTALL_KF_MI_LIST = ${KERNELFILES}
 234
 235    d. INSTALL_KF_MI_LCL_LIST : Installs header file to location that is
 236       available for Apple internal for kernel extensions.
 237       Locations -
 238           $(DSTROOT)/System/Library/Frameworks/Kernel.framework/PrivateHeaders
 239       Definition -
 240           INSTALL_KF_MI_LCL_LIST = ${KERNELFILES} ${PRIVATE_KERNELFILES}
 241
 242 4) If you want to install the header file in a sub-directory of the paths
 243    described in (1), specify the directory name using two variable
 244    INSTALL_MI_DIR and EXPORT_MI_DIR as follows -
 245
 246    INSTALL_MI_DIR = dirname
 247    EXPORT_MI_DIR = dirname
 248
 249 5) A single header file can exist at different locations using the steps
 250    mentioned above.  However it might not be desirable to make all the code
 251    in the header file available at all the locations.  For example, you
 252    want to export a function only to kernel level but not user level.
 253
 254    You can use C language's pre-processor directive (#ifdef, #endif, #ifndef)
 255    to control the text generated before a header file is installed.  The kernel
 256    only includes the code if the conditional macro is TRUE and strips out
 257    code for FALSE conditions from the header file.
 258
 259    Some pre-defined macros and their descriptions are -
 260    a. PRIVATE : If true, code is available to all of the xnu kernel and is
 261       not available in kernel extensions and user level header files.  The
 262       header files installed in all the paths described above in (1) will not
 263       have code enclosed within this macro.
 264
 265    b. KERNEL_PRIVATE : Same as PRIVATE
 266
 267    c. BSD_KERNEL_PRIVATE : If true, code is available to the xnu/bsd part of
 268       the kernel and is not available to rest of the kernel, kernel extensions
 269       and user level header files.  The header files installed in all the
 270       paths described above in (1) will not have code enclosed within this
 271       macro.
 272
 273    d. KERNEL :  If true, code is available only in kernel and kernel
 274       extensions and is not available in user level header files.  Only the
 275       header files installed in following paths will have the code -
 276           $(DSTROOT)/System/Library/Frameworks/Kernel.framework/Headers
 277           $(DSTROOT)/System/Library/Frameworks/Kernel.framework/PrivateHeaders