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   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" SDKROOT=/path/to/SDK
  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" SDKROOT=/path/to/SDK
  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" SDKROOT=/path/to/SDK
  40
  41         or the following is equivalent (ommitted SDKROOT will use /)
  42
  43         make ARCH_CONFIGS=ARM
  44
  45 2) 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
  79 3) 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   $ export SDKROOT=/path/to/SDK
  94   $ make all
  95
  96   Example:
  97     $(OBJROOT)/DEBUG_PPC/osfmk/DEBUG/osfmk.o: pre-linked object for osfmk component
  98     $(OBJROOT)/DEBUG_PPC/mach_kernel: bootable image
  99
 100 4) 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 PPC default RELEASE I386 default" exporthdrs all
 106
 107   or
 108
 109   $ make ARCH_CONFIGS="PPC I386" exporthdrs all
 110
 111   or
 112
 113   $ export ARCH_CONFIGS="PPC I386"
 114   $ make exporthdrs all
 115
 116 5) Verbose make
 117    To display complete tool invocations rather than an abbreviated version,
 118    $ make VERBOSE=YES
 119
 120 6) 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
 126 7) Build check before integration
 127
 128   From the top directory, run:
 129
 130     $ ~rc/bin/buildit . -arch ppc -arch i386 -noinstallsrc -nosum
 131
 132         or for multiple arm builds
 133
 134     $ ~rc/bin/buildit . -noinstallsrc -nosum -- TARGET_CONFIGS="release arm MX31ADS release arm LN2410SBC"
 135
 136         or for default arm build (kernel config DEVELOPMENT and machine config MX31ADS)
 137
 138     $ ~rc/bin/buildit . -arch arm -noinstallsrc -nosum -- TARGET_CONFIGS="release arm MX31ADS release arm LN2410SBC"
 139
 140
 141 8) Creating tags and cscope
 142
 143   Set up your build environment as per instructions in 2a
 144
 145   From the top directory, run:
 146
 147     $ make tags         # this will build ctags and etags on a case-sensitive
 148                         # volume, only ctags on case-insensitive
 149
 150     $ make TAGS         # this will build etags
 151
 152     $ make cscope       # this will build cscope database
 153
 154 9) Other makefile options
 155
 156    $ make MAKEJOBS=-j8    # this will use 8 processes during the build. The default is 2x the number of active cores
 157
 158    $ make -w              # trace recursive make invocations. Useful in combination with VERBOSE=YES
 159
 160 =============================================
 161 B. How to install a new header file from XNU
 162
 163 [Note: This does not cover installing header files in IOKit framework]
 164
 165 1) XNU installs header files at the following locations -
 166         a. $(DSTROOT)/System/Library/Frameworks/Kernel.framework/Headers
 167         b. $(DSTROOT)/System/Library/Frameworks/Kernel.framework/PrivateHeaders
 168         c. $(DSTROOT)/System/Library/Frameworks/System.framework/Headers
 169         d. $(DSTROOT)/System/Library/Frameworks/System.framework/PrivateHeaders
 170         e. $(DSTROOT)/usr/include/
 171
 172         Kernel.framework is used by kernel extensions.  System.framework
 173         and /usr/include are used by user level applications.  The header
 174         files in framework's "PrivateHeaders" are only available for Apple
 175         Internal development.
 176
 177 2) The directory containing the header file should have a Makefile that
 178    creates the list of files that should be installed at different locations.
 179    If you are adding first header file in a directory, you will need to
 180    create Makefile similar to xnu/bsd/sys/Makefile.
 181
 182    Add your header file to the correct file list depending on where you want
 183    to install it.   The default locations where the header files are installed
 184    from each file list are -
 185
 186    a. DATAFILES : To make header file available in user level -
 187           $(DSTROOT)/System/Library/Frameworks/System.framework/Headers
 188           $(DSTROOT)/System/Library/Frameworks/System.framework/PrivateHeaders
 189           $(DSTROOT)/usr/include/
 190
 191    b. PRIVATE_DATAFILES : To make header file available to Apple internal in
 192       user level -
 193           $(DSTROOT)/System/Library/Frameworks/System.framework/PrivateHeaders
 194
 195    c. KERNELFILES : To make header file available in kernel level -
 196           $(DSTROOT)/System/Library/Frameworks/Kernel.framework/Headers
 197           $(DSTROOT)/System/Library/Frameworks/Kernel.framework/PrivateHeaders
 198
 199    d. PRIVATE_KERNELFILES : To make header file available to Apple internal
 200       for kernel extensions -
 201           $(DSTROOT)/System/Library/Frameworks/Kernel.framework/PrivateHeaders
 202
 203 3) The Makefile combines the file lists mentioned above into different
 204    install lists which are used by build system to install the header files.
 205
 206    If the install list that you are interested does not exist, create it
 207    by adding the appropriate file lists.  The default install lists, its
 208    member file lists and their default location are described below -
 209
 210    a. INSTALL_MI_LIST : Installs header file to location that is available to
 211       everyone in user level.
 212       Locations -
 213           $(DSTROOT)/System/Library/Frameworks/System.framework/Headers
 214           $(DSTROOT)/usr/include/
 215       Definition -
 216           INSTALL_MI_LIST = ${DATAFILES}
 217
 218    b. INSTALL_MI_LCL_LIST : Installs header file to location that is available
 219       for Apple internal in user level.
 220       Locations -
 221           $(DSTROOT)/System/Library/Frameworks/System.framework/PrivateHeaders
 222       Definition -
 223           INSTALL_MI_LCL_LIST = ${DATAFILES} ${PRIVATE_DATAFILES}
 224
 225    c. INSTALL_KF_MI_LIST : Installs header file to location that is available
 226       to everyone for kernel extensions.
 227       Locations -
 228           $(DSTROOT)/System/Library/Frameworks/Kernel.framework/Headers
 229       Definition -
 230           INSTALL_KF_MI_LIST = ${KERNELFILES}
 231
 232    d. INSTALL_KF_MI_LCL_LIST : Installs header file to location that is
 233       available for Apple internal for kernel extensions.
 234       Locations -
 235           $(DSTROOT)/System/Library/Frameworks/Kernel.framework/PrivateHeaders
 236       Definition -
 237           INSTALL_KF_MI_LCL_LIST = ${KERNELFILES} ${PRIVATE_KERNELFILES}
 238
 239 4) If you want to install the header file in a sub-directory of the paths
 240    described in (1), specify the directory name using two variable
 241    INSTALL_MI_DIR and EXPORT_MI_DIR as follows -
 242
 243    INSTALL_MI_DIR = dirname
 244    EXPORT_MI_DIR = dirname
 245
 246 5) A single header file can exist at different locations using the steps
 247    mentioned above.  However it might not be desirable to make all the code
 248    in the header file available at all the locations.  For example, you
 249    want to export a function only to kernel level but not user level.
 250
 251    You can use C language's pre-processor directive (#ifdef, #endif, #ifndef)
 252    to control the text generated before a header file is installed.  The kernel
 253    only includes the code if the conditional macro is TRUE and strips out
 254    code for FALSE conditions from the header file.
 255
 256    Some pre-defined macros and their descriptions are -
 257    a. PRIVATE : If true, code is available to all of the xnu kernel and is
 258       not available in kernel extensions and user level header files.  The
 259       header files installed in all the paths described above in (1) will not
 260       have code enclosed within this macro.
 261
 262    b. KERNEL_PRIVATE : Same as PRIVATE
 263
 264    c. BSD_KERNEL_PRIVATE : If true, code is available to the xnu/bsd part of
 265       the kernel and is not available to rest of the kernel, kernel extensions
 266       and user level header files.  The header files installed in all the
 267       paths described above in (1) will not have code enclosed within this
 268       macro.
 269
 270    d. KERNEL :  If true, code is available only in kernel and kernel
 271       extensions and is not available in user level header files.  Only the
 272       header files installed in following paths will have the code -
 273           $(DSTROOT)/System/Library/Frameworks/Kernel.framework/Headers
 274           $(DSTROOT)/System/Library/Frameworks/Kernel.framework/PrivateHeaders