FreeBSD/Linux Kernel Cross Reference
sys/

	Name	Size	Last modified (GMT)	Description
	EXTERNAL_HEADERS/		2012-10-05 07:23:04
	SETUP/		2012-10-05 07:22:52
	bsd/		2012-10-05 07:22:58
	config/		2012-10-05 07:22:52
	iokit/		2012-10-05 07:22:46
	libkern/		2012-10-05 07:22:55
	libsa/		2012-10-05 07:22:45
	libsyscall/		2012-10-05 07:22:53
	makedefs/		2012-10-05 07:23:04
	osfmk/		2012-10-05 07:22:47
	pexpert/		2012-10-05 07:22:51
	security/		2012-10-05 07:22:51
	tools/		2012-10-05 07:22:46
	APPLE_LICENSE	19829 bytes	2006-02-21 03:35:32
	Makefile	1650 bytes	2012-09-17 18:17:25
	README	10511 bytes	2012-09-17 18:17:25
	kgmacros	394761 bytes	2012-09-17 18:17:26
	lldbmacros.py	7829 bytes	2011-11-13 22:07:30

     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 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.
    
    
            /* 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
    
    2) Building a Component
    
      Go to the top directory in your XNU project.
    
      If you are using a sh-style shell, run the following command:
         $ . SETUP/setup.sh
    
      If you are using a csh-style shell, run the following command:
         % source SETUP/setup.csh
    
      This will define the following environmental variables:
        SRCROOT, OBJROOT, DSTROOT, SYMROOT
    
      From a component top directory:
    
        $ make all
    
      This builds a component for all architectures, kernel configurations, and
      machine configurations defined in TARGET_CONFIGS (or alternately ARCH_CONFIGS
      and KERNEL_CONFIGS).
      
      Example:
        $(OBJROOT)/RELEASE_X86_64/osfmk/RELEASE/osfmk.filelist: list of objects in osfmk component
    
      From the component top directory:
    
        $ make mach_kernel
    
      This includes your component in the bootable image, mach_kernel,  and 
      in the kernel binary with symbols, mach_kernel.sys.
    
      WARNING: If a component header file has been modified, you will have to do 
               the above procedure 1.
    
    3) Building DEBUG
    
      Define kernel configuration to DEBUG in your environment or when running a 
      make command.  Then, apply procedures 4, 5
    
      $ make TARGET_CONFIGS="DEBUG X86_64 DEFAULT" all
    
      or
    
      $ make KERNEL_CONFIGS=DEBUG ARCH_CONFIGS=X86_64 all
    
      or
    
      $ export TARGET_CONFIGS="DEBUG X86_64 DEFAULT"
      $ export SDKROOT=/path/to/SDK
      $ make all
    
      Example:
        $(OBJROOT)/DEBUG_X86_64/osfmk/DEBUG/osfmk.filelist: list of objects in osfmk component
        $(OBJROOT)/DEBUG_X86_64/mach_kernel: bootable image
    
    4) Building fat
    
      Define architectures in your environment or when running a make command.
      Apply procedures 3, 4, 5
    
      $ make TARGET_CONFIGS="RELEASE I386 DEFAULT RELEASE X86_64 DEFAULT" exporthdrs all
    
      or
    
      $ make ARCH_CONFIGS="I386 X86_64" exporthdrs all
    
      or
    
      $ export ARCH_CONFIGS="I386 X86_64"
      $ make exporthdrs all
   
   5) Verbose make 
      To display complete tool invocations rather than an abbreviated version,
      $ make VERBOSE=YES
   
   6) 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
   
   7) Build check before integration
   
     From the top directory, run:
   
       $ ~rc/bin/buildit . -arch i386 -arch x86_64 -arch armv7 -arch ppc -noinstallsrc -nosum
   
           
     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:
   
     -project xnu          # the default, builds /mach_kernel, kernel-space
                           # headers, user-space headers, man pages,
                           # symbol-set kexts
   
     -project xnu_debug    # a DEBUG kernel in /AppleInternal with dSYM
   
     -project libkxld      # user-space version of kernel linker
   
     -project libkmod      # static library automatically linked into kexts
   
     -project Libsyscall   # automatically generate BSD syscall stubs
   
   
   
   8) 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 on a case-sensitive
                           # volume, only ctags on case-insensitive
   
       $ make TAGS         # this will build etags
   
       $ make cscope       # this will build cscope database
   
   9) Other makefile options
   
      $ make MAKEJOBS=-j8    # this will use 8 processes during the build. The default is 2x the number of active cores
   
      $ make -w              # trace recursive make invocations. Useful in combination with VERBOSE=YES
   
      $ make BUILD_LTO=1     # build with LLVM Link Time Optimization (experimental)
   
      $ make BUILD_INTEGRATED_ASSEMBLER=1 # build with LLVM integrated assembler (experimental)
   
   =============================================
   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