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 MX31ADS for arm and nothing 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   Here are the valid arm machine configs:
  24         LN2410SBC MX31ADS INTEGRATORCP S5I3000SMDK S5L8900XFPGA S5L8900XRB
  25         OLOCREEK
  26
  27   Examples:
  28         /* make a debug kernel for MX31 arm board */
  29         make TARGET_CONFIGS="debug arm MX31ADS"
  30
  31     $(OBJROOT)/DEBUG_ARM_MX31ADS/osfmk/DEBUG/osfmk.o: pre-linked object for osfmk component
  32     $(OBJROOT)/DEBUG_ARM_MX31ADS/mach_kernel: bootable image
  33
  34         /* make debug and development kernels for MX31 arm board */
  35         make TARGET_CONFIGS="debug arm MX31ADS  development arm MX31ADS"
  36
  37     $(OBJROOT)/DEBUG_ARM_MX31ADS/osfmk/DEBUG/osfmk.o: pre-linked object for osfmk component
  38     $(OBJROOT)/DEBUG_ARM_MX31ADS/mach_kernel: bootable image
  39     $(OBJROOT)/DEVELOPMENT_ARM/osfmk/DEVELOPMENT/osfmk.o: pre-linked object for osfmk component
  40     $(OBJROOT)/DEVELOPMENT_ARM/mach_kernel: bootable image
  41
  42         /* this is all you need to do to build MX31ADS arm with DEVELOPMENT kernel configuration  */
  43         make TARGET_CONFIGS="default arm default"
  44
  45         or the following is equivalent
  46
  47         make ARCH_CONFIGS=ARM
  48
  49 2) Building a Component
  50
  51   Go to the top directory in your XNU project.
  52
  53   If you are using a sh-style shell, run the following command:
  54      $ . SETUP/setup.sh
  55
  56   If you are using a csh-style shell, run the following command:
  57      % source SETUP/setup.csh
  58
  59   This will define the following environmental variables:
  60     SRCROOT, OBJROOT, DSTROOT, SYMROOT
  61
  62   From a component top directory:
  63
  64     $ make all
  65
  66   This builds a component for all architectures, kernel configurations, and
  67   machine configurations defined in TARGET_CONFIGS (or alternately ARCH_CONFIGS
  68   and KERNEL_CONFIGS).
  69
  70   Example:
  71     $(OBJROOT)/RELEASE_PPC/osfmk/RELEASE/osfmk.o: pre-linked object for osfmk component
  72
  73   From the component top directory:
  74
  75     $ make mach_kernel
  76
  77   This includes your component in the bootable image, mach_kernel,  and
  78   in the kernel binary with symbols, mach_kernel.sys.
  79
  80   WARNING: If a component header file has been modified, you will have to do
  81            the above procedure 1.
  82
  83 3) Building DEBUG
  84
  85   Define kernel configuration to DEBUG in your environment or when running a
  86   make command.  Then, apply procedures 4, 5
  87
  88   $ make TARGET_CONFIGS="DEBUG PPC DEFAULT" all
  89
  90   or
  91
  92   $ make KERNEL_CONFIGS=DEBUG all
  93
  94   or
  95
  96   $ export TARGET_CONFIGS="DEBUG ARM MX31ADS"
  97   $ make all
  98
  99   Example:
 100     $(OBJROOT)/DEBUG_PPC/osfmk/DEBUG/osfmk.o: pre-linked object for osfmk component
 101     $(OBJROOT)/DEBUG_PPC/mach_kernel: bootable image
 102
 103 4) Building fat
 104
 105   Define architectures in your environment or when running a make command.
 106   Apply procedures 3, 4, 5
 107
 108   $ make TARGET_CONFIGS="RELEASE PPC default RELEASE I386 default" exporthdrs all
 109
 110   or
 111
 112   $ make ARCH_CONFIGS="PPC I386" exporthdrs all
 113
 114   or
 115
 116   $ export ARCH_CONFIGS="PPC I386"
 117   $ make exporthdrs all
 118
 119 5) Verbose make
 120    To display complete tool invocations rather than an abbreviated version,
 121    $ make VERBOSE=YES
 122
 123 6) Debug information formats
 124    By default, a DWARF debug information repository is created during the install phase; this is a "bundle" named mach_kernel.dSYM
 125    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.
 126    $ export BUILD_STABS=1
 127    $ make
 128
 129 7) Build check before integration
 130
 131   From the top directory, run:
 132
 133     $ ~rc/bin/buildit . -arch ppc -arch i386 -noinstallsrc -nosum
 134
 135         or for multiple arm builds
 136
 137     $ ~rc/bin/buildit . -noinstallsrc -nosum -- TARGET_CONFIGS="release arm MX31ADS release arm LN2410SBC"
 138
 139         or for default arm build (kernel config DEVELOPMENT and machine config MX31ADS)
 140
 141     $ ~rc/bin/buildit . -arch arm -noinstallsrc -nosum -- TARGET_CONFIGS="release arm MX31ADS release arm LN2410SBC"
 142
 143
 144 8) Creating tags and cscope
 145
 146   Set up your build environment as per instructions in 2a
 147
 148   From the top directory, run:
 149
 150     $ make tags         # this will build ctags and etags on a case-sensitive
 151                         # volume, only ctags on case-insensitive
 152
 153     $ make TAGS         # this will build etags
 154
 155     $ make cscope       # this will build cscope database
 156
 157 =============================================
 158 B. How to install a new header file from XNU
 159
 160 [Note: This does not covers installing header file in IOKit framework]
 161
 162 1) XNU installs header files at the following locations -
 163         a. $(DSTROOT)/System/Library/Frameworks/Kernel.framework/Headers
 164         b. $(DSTROOT)/System/Library/Frameworks/Kernel.framework/PrivateHeaders
 165         c. $(DSTROOT)/System/Library/Frameworks/System.framework/Headers
 166         d. $(DSTROOT)/System/Library/Frameworks/System.framework/PrivateHeaders
 167         e. $(DSTROOT)/usr/include/
 168
 169         Kernel.framework is used by kernel extensions.  System.framework
 170         and /usr/include are used by user level applications.  The header
 171         files in framework's "PrivateHeaders" are only available for Apple
 172         Internal development.
 173
 174 2) The directory containing the header file should have a Makefile that
 175    creates the list of files that should be installed at different locations.
 176    If you are adding first header file in a directory, you will need to
 177    create Makefile similar to xnu/bsd/sys/Makefile.
 178
 179    Add your header file to the correct file list depending on where you want
 180    to install it.   The default locations where the header files are installed
 181    from each file list are -
 182
 183    a. DATAFILES : To make header file available in user level -
 184           $(DSTROOT)/System/Library/Frameworks/System.framework/Headers
 185           $(DSTROOT)/System/Library/Frameworks/System.framework/PrivateHeaders
 186           $(DSTROOT)/usr/include/
 187
 188    b. PRIVATE_DATAFILES : To make header file available to Apple internal in
 189       user level -
 190           $(DSTROOT)/System/Library/Frameworks/System.framework/PrivateHeaders
 191
 192    c. KERNELFILES : To make header file available in kernel level -
 193           $(DSTROOT)/System/Library/Frameworks/Kernel.framework/Headers
 194           $(DSTROOT)/System/Library/Frameworks/Kernel.framework/PrivateHeaders
 195
 196    d. PRIVATE_KERNELFILES : To make header file available to Apple internal
 197       for kernel extensions -
 198           $(DSTROOT)/System/Library/Frameworks/Kernel.framework/PrivateHeaders
 199
 200 3) The Makefile combines the file lists mentioned above into different
 201    install lists which are used by build system to install the header files.
 202
 203    If the install list that you are interested does not exists, create it
 204    by adding the appropriate file lists.  The default install lists, its
 205    member file lists and their default location are described below -
 206
 207    a. INSTALL_MI_LIST : Installs header file to location that is available to
 208       everyone in user level.
 209       Locations -
 210           $(DSTROOT)/System/Library/Frameworks/System.framework/Headers
 211           $(DSTROOT)/usr/include/
 212       Definition -
 213           INSTALL_MI_LIST = ${DATAFILES}
 214
 215    b. INSTALL_MI_LCL_LIST : Installs header file to location that is available
 216       for Apple internal in user level.
 217       Locations -
 218           $(DSTROOT)/System/Library/Frameworks/System.framework/PrivateHeaders
 219       Definition -
 220           INSTALL_MI_LCL_LIST = ${DATAFILES} ${PRIVATE_DATAFILES}
 221
 222    c. INSTALL_KF_MI_LIST : Installs header file to location that is available
 223       to everyone for kernel extensions.
 224       Locations -
 225           $(DSTROOT)/System/Library/Frameworks/Kernel.framework/Headers
 226       Definition -
 227           INSTALL_KF_MI_LIST = ${KERNELFILES}
 228
 229    d. INSTALL_KF_MI_LCL_LIST : Installs header file to location that is
 230       available for Apple internal for kernel extensions.
 231       Locations -
 232           $(DSTROOT)/System/Library/Frameworks/Kernel.framework/PrivateHeaders
 233       Definition -
 234           INSTALL_KF_MI_LCL_LIST = ${KERNELFILES} ${PRIVATE_KERNELFILES}
 235
 236 4) If you want to install the header file in a sub-directory of the paths
 237    described in (1), specify the directory name using two variable
 238    INSTALL_MI_DIR and EXPORT_MI_DIR as follows -
 239
 240    INSTALL_MI_DIR = dirname
 241    EXPORT_MI_DIR = dirname
 242
 243 5) A single header file can exist at different locations using the steps
 244    mentioned above.  However it might not be desirable to make all the code
 245    in the header file available at all the locations.  For example, you
 246    want to export a function only to kernel level but not user level.
 247
 248    You can use C language's pre-processor directive (#ifdef, #endif, #ifndef)
 249    to control the text generated before a header file is installed.  The kernel
 250    only includes the code if the conditional macro is TRUE and strips out
 251    code for FALSE conditions from the header file.
 252
 253    Some pre-defined macros and their descriptions are -
 254    a. PRIVATE : If true, code is available to all of the xnu kernel and is
 255       not available in kernel extensions and user level header files.  The
 256       header files installed in all the paths described above in (1) will not
 257       have code enclosed within this macro.
 258
 259    b. KERNEL_PRIVATE : Same as PRIVATE
 260
 261    c. BSD_KERNEL_PRIVATE : If true, code is available to the xnu/bsd part of
 262       the kernel and is not available to rest of the kernel, kernel extensions
 263       and user level header files.  The header files installed in all the
 264       paths described above in (1) will not have code enclosed within this
 265       macro.
 266
 267    d. KERNEL :  If true, code is available only in kernel and kernel
 268       extensions and is not available in user level header files.  Only the
 269       header files installed in following paths will have the code -
 270           $(DSTROOT)/System/Library/Frameworks/Kernel.framework/Headers
 271           $(DSTROOT)/System/Library/Frameworks/Kernel.framework/PrivateHeaders