xnu-3247.1.106.tar.gz

[apple/xnu.git] / README

diff --git a/README b/README
index 9ab5b012d8d964afedfa405ce815f02804ac9cb5..1294b6726f2fb316d8d94feb175bc84677d4ad3e 100644 (file)
--- a/README
+++ b/README
@@ -15,133 +15,97 @@ A. How to build XNU:
 
   By default, architecture defaults to the build machine 
   architecture, and the kernel configuration is set to build for DEVELOPMENT.
 
   By default, architecture defaults to the build machine 
   architecture, and the kernel configuration is set to build for DEVELOPMENT.

-  The machine configuration defaults to MX31ADS for arm and nothing for i386 and ppc.

   
   This will also create a bootable image, mach_kernel,  and a kernel binary 
   with symbols, mach_kernel.sys.
 
   
   This will also create a bootable image, mach_kernel,  and a kernel binary 
   with symbols, mach_kernel.sys.
 

-  Here are the valid arm machine configs:
-       LN2410SBC MX31ADS INTEGRATORCP S5I3000SMDK S5L8900XFPGA S5L8900XRB
-       OLOCREEK
-       
-  Examples:
-       /* make a debug kernel for MX31 arm board */
-       make TARGET_CONFIGS="debug arm MX31ADS"
-       
-    $(OBJROOT)/DEBUG_ARM_MX31ADS/osfmk/DEBUG/osfmk.o: pre-linked object for osfmk component
-    $(OBJROOT)/DEBUG_ARM_MX31ADS/mach_kernel: bootable image
-
-       /* make debug and development kernels for MX31 arm board */
-       make TARGET_CONFIGS="debug arm MX31ADS  development arm MX31ADS"
-       
-    $(OBJROOT)/DEBUG_ARM_MX31ADS/osfmk/DEBUG/osfmk.o: pre-linked object for osfmk component
-    $(OBJROOT)/DEBUG_ARM_MX31ADS/mach_kernel: bootable image
-    $(OBJROOT)/DEVELOPMENT_ARM/osfmk/DEVELOPMENT/osfmk.o: pre-linked object for osfmk component
-    $(OBJROOT)/DEVELOPMENT_ARM/mach_kernel: bootable image

 
 

-       /* this is all you need to do to build MX31ADS arm with DEVELOPMENT kernel configuration  */
-       make TARGET_CONFIGS="default arm default"
+       /* 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
+       or the following is equivalent (ommitted SDKROOT will use /)

        
        

-       make ARCH_CONFIGS=ARM
-
-2) Building a Component
-
-  Go to the top directory in your XNU project.
+       make ARCH_CONFIGS=X86_64

 
 

-  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_PPC/osfmk/RELEASE/osfmk.o: pre-linked object for 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
+2) Building DEBUG

 
   Define kernel configuration to DEBUG in your environment or when running a 
   make command.  Then, apply procedures 4, 5
 
 
   Define kernel configuration to DEBUG in your environment or when running a 
   make command.  Then, apply procedures 4, 5
 

-  $ make TARGET_CONFIGS="DEBUG PPC DEFAULT" all
+  $ make TARGET_CONFIGS="DEBUG X86_64 DEFAULT" all

 
   or
 
 
   or
 

-  $ make KERNEL_CONFIGS=DEBUG all
+  $ make KERNEL_CONFIGS=DEBUG ARCH_CONFIGS=X86_64 all

 
   or
 
 
   or
 

-  $ export TARGET_CONFIGS="DEBUG ARM MX31ADS"
+  $ export TARGET_CONFIGS="DEBUG X86_64 DEFAULT"
+  $ export SDKROOT=/path/to/SDK

   $ make all
 
   Example:
   $ make all
 
   Example:

-    $(OBJROOT)/DEBUG_PPC/osfmk/DEBUG/osfmk.o: pre-linked object for osfmk component
-    $(OBJROOT)/DEBUG_PPC/mach_kernel: bootable image
+    $(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
+3) Building fat

 
   Define architectures in your environment or when running a make command.
   Apply procedures 3, 4, 5
 
 
   Define architectures in your environment or when running a make command.
   Apply procedures 3, 4, 5
 

-  $ make TARGET_CONFIGS="RELEASE PPC default RELEASE I386 default" exporthdrs all
+  $ make TARGET_CONFIGS="RELEASE I386 DEFAULT RELEASE X86_64 DEFAULT" exporthdrs all

 
   or
 
 
   or
 

-  $ make ARCH_CONFIGS="PPC I386" exporthdrs all
+  $ make ARCH_CONFIGS="I386 X86_64" exporthdrs all

 
   or
 
 
   or
 

-  $ export ARCH_CONFIGS="PPC I386"
+  $ export ARCH_CONFIGS="I386 X86_64"

   $ make exporthdrs all
 
   $ make exporthdrs all
 

-5) Verbose make 
+4) Verbose make 

    To display complete tool invocations rather than an abbreviated version,
    $ make VERBOSE=YES
 
    To display complete tool invocations rather than an abbreviated version,
    $ make VERBOSE=YES
 

-6) Debug information formats
+5) 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
 
    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
+6) Build check before integration

 
   From the top directory, run:
 
 
   From the top directory, run:
 

-    $ ~rc/bin/buildit . -arch ppc -arch i386 -noinstallsrc -nosum
-       
-       or for multiple arm builds
-       
-    $ ~rc/bin/buildit . -noinstallsrc -nosum -- TARGET_CONFIGS="release arm MX31ADS release arm LN2410SBC"
-       
-       or for default arm build (kernel config DEVELOPMENT and machine config MX31ADS)
-       
-    $ ~rc/bin/buildit . -arch arm -noinstallsrc -nosum -- TARGET_CONFIGS="release arm MX31ADS release arm LN2410SBC"
+    $ ~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 -buildAlias argument to ~rc/bin/buildit, which
+  can be one of:

 
 

-8) Creating tags and cscope
+  -buildAlias xnu            # the default, builds /mach_kernel, kernel-space
+                             # headers, user-space headers, man pages,
+                             # symbol-set kexts
+
+  -buildAlias xnu_debug      # a DEBUG kernel in /AppleInternal with dSYM
+
+  -buildAlias libkxld        # user-space version of kernel linker
+
+  -buildAlias libkmod        # static library automatically linked into kexts
+
+  -buildAlias Libsyscall     # automatically generate BSD syscall stubs
+
+  -buildAlias xnu_quick_test # install xnu unit tests
+
+
+
+7) Creating tags and cscope

 
   Set up your build environment as per instructions in 2a
 
 
   Set up your build environment as per instructions in 2a
 


@@ -154,17 +118,40 @@ A. How to build XNU:
 
     $ make cscope      # this will build cscope database
 
 
     $ make cscope      # this will build cscope database
 

+8) Reindenting files
+
+  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
+
+  Note: clang-format binary may not be part of base installation. It can be compiled from llvm clang sources and is reachable in $PATH.
+
+  From the top directory, run:
+
+   $ make reindent      # reindent all source files using clang format.
+
+
+9) Other makefile options
+
+   $ make MAKEJOBS=-j8    # this will use 8 processes during the build. The default is 2x the number of active CPUS.
+   $ make -j8             # the standard command-line option is also accepted
+
+   $ make -w              # trace recursive make invocations. Useful in combination with VERBOSE=YES
+
+   $ make BUILD_LTO=0    # build without LLVM Link Time Optimization
+
+   $ make REMOTEBUILD=user@remotehost # perform build on remote host
+
+   $ make BUILD_JSON_COMPILATION_DATABASE=1 # Build Clang JSON Compilation Database
+

 =============================================
 B. How to install a new header file from XNU
 
 =============================================
 B. How to install a new header file from XNU
 

-[Note: This does not covers installing header file in IOKit framework]
+[To install IOKit headers, see additional comments in iokit/IOKit/Makefile.]

 
 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
 
 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
+       c. $(DSTROOT)/usr/include/

        d. $(DSTROOT)/System/Library/Frameworks/System.framework/PrivateHeaders
        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 
 
        Kernel.framework is used by kernel extensions.  System.framework 
        and /usr/include are used by user level applications.  The header 


@@ -181,9 +168,7 @@ B. How to install a new header file from XNU
    from each file list are -
 
    a. DATAFILES : To make header file available in user level -
    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/
+         $(DSTROOT)/usr/include

 
    b. PRIVATE_DATAFILES : To make header file available to Apple internal in 
       user level -
 
    b. PRIVATE_DATAFILES : To make header file available to Apple internal in 
       user level -


@@ -200,24 +185,23 @@ B. How to install a new header file from XNU
 3) The Makefile combines the file lists mentioned above into different 
    install lists which are used by build system to install the header files.
 
 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 exists, create it
+   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 - 
 
    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 
+   a. INSTALL_MI_LIST : Installs header file to a location that is available to

       everyone in user level. 
       Locations -
       everyone in user level. 
       Locations -

-         $(DSTROOT)/System/Library/Frameworks/System.framework/Headers
-         $(DSTROOT)/usr/include/
+         $(DSTROOT)/usr/include

       Definition -
          INSTALL_MI_LIST = ${DATAFILES}
 
       Definition -
          INSTALL_MI_LIST = ${DATAFILES}
 

-   b. INSTALL_MI_LCL_LIST : Installs header file to location that is available
+   b. INSTALL_MI_LCL_LIST : Installs header file to a location that is available

       for Apple internal in user level.
       Locations -
          $(DSTROOT)/System/Library/Frameworks/System.framework/PrivateHeaders
       Definition -
       for Apple internal in user level.
       Locations -
          $(DSTROOT)/System/Library/Frameworks/System.framework/PrivateHeaders
       Definition -

-         INSTALL_MI_LCL_LIST = ${DATAFILES} ${PRIVATE_DATAFILES}
+         INSTALL_MI_LCL_LIST = ${PRIVATE_DATAFILES}

 
    c. INSTALL_KF_MI_LIST : Installs header file to location that is available
       to everyone for kernel extensions.
 
    c. INSTALL_KF_MI_LIST : Installs header file to location that is available
       to everyone for kernel extensions.