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 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
  51 3) 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
  67 4) Verbose make
  68    To display complete tool invocations rather than an abbreviated version,
  69    $ make VERBOSE=YES
  70
  71 5) 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
  77 6) 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 -buildAlias argument to ~rc/bin/buildit, which
  90   can be one of:
  91
  92   -buildAlias xnu            # the default, builds /mach_kernel, kernel-space
  93                              # headers, user-space headers, man pages,
  94                              # symbol-set kexts
  95
  96   -buildAlias xnu_debug      # a DEBUG kernel in /AppleInternal with dSYM
  97
  98   -buildAlias libkxld        # user-space version of kernel linker
  99
 100   -buildAlias libkmod        # static library automatically linked into kexts
 101
 102   -buildAlias Libsyscall     # automatically generate BSD syscall stubs
 103
 104   -buildAlias xnu_quick_test # install xnu unit tests
 105
 106
 107
 108 7) 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
 121 8) Reindenting files
 122
 123   Source files can be reindented using clang-format setup in .clang-format. XNU follow a variant of WebKit style for source code formatting. Please refer to format styles at http://www.webkit.org/coding/coding-style.html. Further options about style options is available at http://clang.llvm.org/docs/ClangFormatStyleOptions.html
 124
 125   Note: clang-format binary may not be part of base installation. It can be compiled from llvm clang sources and is reachable in $PATH.
 126
 127   From the top directory, run:
 128
 129    $ make reindent      # reindent all source files using clang format.
 130
 131
 132 9) Other makefile options
 133
 134    $ make MAKEJOBS=-j8    # this will use 8 processes during the build. The default is 2x the number of active CPUS.
 135    $ make -j8             # the standard command-line option is also accepted
 136
 137    $ make -w              # trace recursive make invocations. Useful in combination with VERBOSE=YES
 138
 139    $ make BUILD_LTO=0     # build without LLVM Link Time Optimization
 140
 141    $ make REMOTEBUILD=user@remotehost # perform build on remote host
 142
 143    $ make BUILD_JSON_COMPILATION_DATABASE=1 # Build Clang JSON Compilation Database
 144
 145 =============================================
 146 B. How to install a new header file from XNU
 147
 148 [To install IOKit headers, see additional comments in iokit/IOKit/Makefile.]
 149
 150 1) XNU installs header files at the following locations -
 151         a. $(DSTROOT)/System/Library/Frameworks/Kernel.framework/Headers
 152         b. $(DSTROOT)/System/Library/Frameworks/Kernel.framework/PrivateHeaders
 153         c. $(DSTROOT)/usr/include/
 154         d. $(DSTROOT)/System/Library/Frameworks/System.framework/PrivateHeaders
 155
 156         Kernel.framework is used by kernel extensions.  System.framework
 157         and /usr/include are used by user level applications.  The header
 158         files in framework's "PrivateHeaders" are only available for Apple
 159         Internal development.
 160
 161 2) The directory containing the header file should have a Makefile that
 162    creates the list of files that should be installed at different locations.
 163    If you are adding first header file in a directory, you will need to
 164    create Makefile similar to xnu/bsd/sys/Makefile.
 165
 166    Add your header file to the correct file list depending on where you want
 167    to install it.   The default locations where the header files are installed
 168    from each file list are -
 169
 170    a. DATAFILES : To make header file available in user level -
 171           $(DSTROOT)/usr/include
 172
 173    b. PRIVATE_DATAFILES : To make header file available to Apple internal in
 174       user level -
 175           $(DSTROOT)/System/Library/Frameworks/System.framework/PrivateHeaders
 176
 177    c. KERNELFILES : To make header file available in kernel level -
 178           $(DSTROOT)/System/Library/Frameworks/Kernel.framework/Headers
 179           $(DSTROOT)/System/Library/Frameworks/Kernel.framework/PrivateHeaders
 180
 181    d. PRIVATE_KERNELFILES : To make header file available to Apple internal
 182       for kernel extensions -
 183           $(DSTROOT)/System/Library/Frameworks/Kernel.framework/PrivateHeaders
 184
 185 3) The Makefile combines the file lists mentioned above into different
 186    install lists which are used by build system to install the header files.
 187
 188    If the install list that you are interested does not exist, create it
 189    by adding the appropriate file lists.  The default install lists, its
 190    member file lists and their default location are described below -
 191
 192    a. INSTALL_MI_LIST : Installs header file to a location that is available to
 193       everyone in user level.
 194       Locations -
 195           $(DSTROOT)/usr/include
 196       Definition -
 197           INSTALL_MI_LIST = ${DATAFILES}
 198
 199    b. INSTALL_MI_LCL_LIST : Installs header file to a location that is available
 200       for Apple internal in user level.
 201       Locations -
 202           $(DSTROOT)/System/Library/Frameworks/System.framework/PrivateHeaders
 203       Definition -
 204           INSTALL_MI_LCL_LIST = ${PRIVATE_DATAFILES}
 205
 206    c. INSTALL_KF_MI_LIST : Installs header file to location that is available
 207       to everyone for kernel extensions.
 208       Locations -
 209           $(DSTROOT)/System/Library/Frameworks/Kernel.framework/Headers
 210       Definition -
 211           INSTALL_KF_MI_LIST = ${KERNELFILES}
 212
 213    d. INSTALL_KF_MI_LCL_LIST : Installs header file to location that is
 214       available for Apple internal for kernel extensions.
 215       Locations -
 216           $(DSTROOT)/System/Library/Frameworks/Kernel.framework/PrivateHeaders
 217       Definition -
 218           INSTALL_KF_MI_LCL_LIST = ${KERNELFILES} ${PRIVATE_KERNELFILES}
 219
 220 4) If you want to install the header file in a sub-directory of the paths
 221    described in (1), specify the directory name using two variable
 222    INSTALL_MI_DIR and EXPORT_MI_DIR as follows -
 223
 224    INSTALL_MI_DIR = dirname
 225    EXPORT_MI_DIR = dirname
 226
 227 5) A single header file can exist at different locations using the steps
 228    mentioned above.  However it might not be desirable to make all the code
 229    in the header file available at all the locations.  For example, you
 230    want to export a function only to kernel level but not user level.
 231
 232    You can use C language's pre-processor directive (#ifdef, #endif, #ifndef)
 233    to control the text generated before a header file is installed.  The kernel
 234    only includes the code if the conditional macro is TRUE and strips out
 235    code for FALSE conditions from the header file.
 236
 237    Some pre-defined macros and their descriptions are -
 238    a. PRIVATE : If true, code is available to all of the xnu kernel and is
 239       not available in kernel extensions and user level header files.  The
 240       header files installed in all the paths described above in (1) will not
 241       have code enclosed within this macro.
 242
 243    b. KERNEL_PRIVATE : Same as PRIVATE
 244
 245    c. BSD_KERNEL_PRIVATE : If true, code is available to the xnu/bsd part of
 246       the kernel and is not available to rest of the kernel, kernel extensions
 247       and user level header files.  The header files installed in all the
 248       paths described above in (1) will not have code enclosed within this
 249       macro.
 250
 251    d. KERNEL :  If true, code is available only in kernel and kernel
 252       extensions and is not available in user level header files.  Only the
 253       header files installed in following paths will have the code -
 254           $(DSTROOT)/System/Library/Frameworks/Kernel.framework/Headers
 255           $(DSTROOT)/System/Library/Frameworks/Kernel.framework/PrivateHeaders