+=============================================
+B. How to install a new header file from XNU
+
+[Note: This does not covers installing header file 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 exists, 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
projects / apple / xnu.git / blobdiff