The Design and Implementation of the FreeBSD Operating System, Second Edition
Now available: The Design and Implementation of the FreeBSD Operating System (Second Edition)


[ source navigation ] [ identifier search ] [ freetext search ] [ file search ] [ list types ] [ track identifier ]

FreeBSD/Linux Kernel Cross Reference
sys/

Version: -  FREEBSD  -  FREEBSD-13-STABLE  -  FREEBSD-13-0  -  FREEBSD-12-STABLE  -  FREEBSD-12-0  -  FREEBSD-11-STABLE  -  FREEBSD-11-0  -  FREEBSD-10-STABLE  -  FREEBSD-10-0  -  FREEBSD-9-STABLE  -  FREEBSD-9-0  -  FREEBSD-8-STABLE  -  FREEBSD-8-0  -  FREEBSD-7-STABLE  -  FREEBSD-7-0  -  FREEBSD-6-STABLE  -  FREEBSD-6-0  -  FREEBSD-5-STABLE  -  FREEBSD-5-0  -  FREEBSD-4-STABLE  -  FREEBSD-3-STABLE  -  FREEBSD22  -  l41  -  OPENBSD  -  linux-2.6  -  MK84  -  PLAN9  -  xnu-8792 
SearchContext: -  none  -  3  -  10 

Name Size Last modified (GMT) Description
Folder EXTERNAL_HEADERS/ 2011-10-11 22:52:56
Folder SETUP/ 2011-10-11 22:52:56
Folder bsd/ 2011-10-11 22:52:56
Folder config/ 2011-10-11 22:52:57
Folder iokit/ 2011-10-11 22:52:56
Folder libkern/ 2011-10-11 22:52:57
Folder libsa/ 2011-10-11 22:52:57
Folder libsyscall/ 2011-08-10 02:17:41
Folder makedefs/ 2011-10-11 22:52:57
Folder osfmk/ 2011-10-11 22:52:57
Folder pexpert/ 2011-10-11 22:52:57
Folder security/ 2011-10-11 22:52:57
Folder tools/ 2011-10-11 22:52:55
File APPLE_LICENSE 19829 bytes 2006-02-21 03:35:32
File Makefile 1571 bytes 2011-10-11 22:52:56
File README 10348 bytes 2011-10-11 22:52:56
File kgmacros 382312 bytes 2011-10-11 22:52:57

    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 Libsyscall   # automatically generate BSD syscall stubs
  135 
  136 
  137 
  138 8) Creating tags and cscope
  139 
  140   Set up your build environment as per instructions in 2a
  141 
  142   From the top directory, run:
  143 
  144     $ make tags         # this will build ctags and etags on a case-sensitive
  145                         # volume, only ctags on case-insensitive
  146 
  147     $ make TAGS         # this will build etags
  148 
  149     $ make cscope       # this will build cscope database
  150 
  151 9) Other makefile options
  152 
  153    $ make MAKEJOBS=-j8    # this will use 8 processes during the build. The default is 2x the number of active cores
  154 
  155    $ make -w              # trace recursive make invocations. Useful in combination with VERBOSE=YES
  156 
  157    $ make BUILD_LTO=1     # built with LLVM Link Time Optimization (experimental)
  158 
  159 =============================================
  160 B. How to install a new header file from XNU
  161 
  162 [Note: This does not cover installing header files in IOKit framework]
  163 
  164 1) XNU installs header files at the following locations -
  165         a. $(DSTROOT)/System/Library/Frameworks/Kernel.framework/Headers
  166         b. $(DSTROOT)/System/Library/Frameworks/Kernel.framework/PrivateHeaders
  167         c. $(DSTROOT)/System/Library/Frameworks/System.framework/Headers
  168         d. $(DSTROOT)/System/Library/Frameworks/System.framework/PrivateHeaders
  169         e. $(DSTROOT)/usr/include/
  170 
  171         Kernel.framework is used by kernel extensions.  System.framework 
  172         and /usr/include are used by user level applications.  The header 
  173         files in framework's "PrivateHeaders" are only available for Apple 
  174         Internal development.
  175 
  176 2) The directory containing the header file should have a Makefile that 
  177    creates the list of files that should be installed at different locations.
  178    If you are adding first header file in a directory, you will need to 
  179    create Makefile similar to xnu/bsd/sys/Makefile.
  180 
  181    Add your header file to the correct file list depending on where you want 
  182    to install it.   The default locations where the header files are installed 
  183    from each file list are -
  184 
  185    a. DATAFILES : To make header file available in user level -
  186           $(DSTROOT)/System/Library/Frameworks/System.framework/Headers
  187           $(DSTROOT)/System/Library/Frameworks/System.framework/PrivateHeaders
  188           $(DSTROOT)/usr/include/
  189 
  190    b. PRIVATE_DATAFILES : To make header file available to Apple internal in 
  191       user level -
  192           $(DSTROOT)/System/Library/Frameworks/System.framework/PrivateHeaders
  193 
  194    c. KERNELFILES : To make header file available in kernel level - 
  195           $(DSTROOT)/System/Library/Frameworks/Kernel.framework/Headers
  196           $(DSTROOT)/System/Library/Frameworks/Kernel.framework/PrivateHeaders
  197 
  198    d. PRIVATE_KERNELFILES : To make header file available to Apple internal 
  199       for kernel extensions - 
  200           $(DSTROOT)/System/Library/Frameworks/Kernel.framework/PrivateHeaders
  201 
  202 3) The Makefile combines the file lists mentioned above into different 
  203    install lists which are used by build system to install the header files.
  204 
  205    If the install list that you are interested does not exist, create it
  206    by adding the appropriate file lists.  The default install lists, its 
  207    member file lists and their default location are described below - 
  208 
  209    a. INSTALL_MI_LIST : Installs header file to location that is available to 
  210       everyone in user level. 
  211       Locations -
  212           $(DSTROOT)/System/Library/Frameworks/System.framework/Headers
  213           $(DSTROOT)/usr/include/
  214       Definition -
  215           INSTALL_MI_LIST = ${DATAFILES}
  216 
  217    b. INSTALL_MI_LCL_LIST : Installs header file to location that is available
  218       for Apple internal in user level.
  219       Locations -
  220           $(DSTROOT)/System/Library/Frameworks/System.framework/PrivateHeaders
  221       Definition -
  222           INSTALL_MI_LCL_LIST = ${DATAFILES} ${PRIVATE_DATAFILES}
  223 
  224    c. INSTALL_KF_MI_LIST : Installs header file to location that is available
  225       to everyone for kernel extensions.
  226       Locations -
  227           $(DSTROOT)/System/Library/Frameworks/Kernel.framework/Headers
  228       Definition -
  229           INSTALL_KF_MI_LIST = ${KERNELFILES}
  230 
  231    d. INSTALL_KF_MI_LCL_LIST : Installs header file to location that is 
  232       available for Apple internal for kernel extensions.
  233       Locations -
  234           $(DSTROOT)/System/Library/Frameworks/Kernel.framework/PrivateHeaders
  235       Definition -
  236           INSTALL_KF_MI_LCL_LIST = ${KERNELFILES} ${PRIVATE_KERNELFILES}
  237 
  238 4) If you want to install the header file in a sub-directory of the paths 
  239    described in (1), specify the directory name using two variable 
  240    INSTALL_MI_DIR and EXPORT_MI_DIR as follows - 
  241 
  242    INSTALL_MI_DIR = dirname
  243    EXPORT_MI_DIR = dirname
  244 
  245 5) A single header file can exist at different locations using the steps 
  246    mentioned above.  However it might not be desirable to make all the code
  247    in the header file available at all the locations.  For example, you 
  248    want to export a function only to kernel level but not user level.
  249 
  250    You can use C language's pre-processor directive (#ifdef, #endif, #ifndef)
  251    to control the text generated before a header file is installed.  The kernel 
  252    only includes the code if the conditional macro is TRUE and strips out 
  253    code for FALSE conditions from the header file.  
  254 
  255    Some pre-defined macros and their descriptions are -
  256    a. PRIVATE : If true, code is available to all of the xnu kernel and is 
  257       not available in kernel extensions and user level header files.  The 
  258       header files installed in all the paths described above in (1) will not 
  259       have code enclosed within this macro.
  260 
  261    b. KERNEL_PRIVATE : Same as PRIVATE
  262 
  263    c. BSD_KERNEL_PRIVATE : If true, code is available to the xnu/bsd part of 
  264       the kernel and is not available to rest of the kernel, kernel extensions 
  265       and user level header files.  The header files installed in all the 
  266       paths described above in (1) will not have code enclosed within this 
  267       macro.
  268 
  269    d. KERNEL :  If true, code is available only in kernel and kernel 
  270       extensions and is not available in user level header files.  Only the 
  271       header files installed in following paths will have the code - 
  272           $(DSTROOT)/System/Library/Frameworks/Kernel.framework/Headers
  273           $(DSTROOT)/System/Library/Frameworks/Kernel.framework/PrivateHeaders

[ source navigation ] [ identifier search ] [ freetext search ] [ file search ] [ list types ] [ track identifier ]


This page is part of the FreeBSD/Linux Linux Kernel Cross-Reference, and was automatically generated using a modified version of the LXR engine.