위치:

* `<sdkroot>`: 디스크에 있는 macOS SDK 경로입니다. (기본값: `/`)
* `<variant>`: `debug`, `development`, `release`, `profile` 중 하나이며, 커널 코드 전체에서 컴파일 플래그와 어서트(assert)를 구성합니다.
* `<arch>`: 빌드할 아키텍처를 지정합니다. (예: `X86_64`)

실행 중인 OS와 동일한 아키텍처로 커널을 빌드하려면 다음을 입력하세요.```text
make SDKROOT=macosx.internal

> 참고: 기본적으로 아키텍처는 빌드 머신의 아키텍처로 설정되며, 기본 커널 구성은 `DEVELOPMENT`용으로 빌드하도록 설정됩니다.

이렇게 하면 부팅 가능한 이미지, kernel.[config], 그리고 심볼이 포함된 커널 바이너리인 kernel.[config].unstripped도 생성됩니다.

커널을 DSTROOT에 설치하려면 `install_kernels` 타겟을 사용하세요:```text
make install_kernels DSTROOT=/tmp/xnu-dst

`DEVELOPMENT`와 `ARM64`를 적절한 빌드 및 플랫폼으로 바꾸는 것을 잊지 마세요.

> 추가 플래그: `EXTRA_CFLAGS` 빌드 설정을 사용하여 명령줄에서 C 컴파일러에 추가 플래그를 전달할 수 있습니다. 이 플래그는 기본 `CFLAGS`에 추가되며, 설정의 기본값은 빈 문자열입니다.
>
> 이 설정을 사용하면 예를 들어 전처리기 매크로로 보호되는 디버깅 코드를 선택적으로 활성화할 수 있습니다. 사용 예...
>
> ```text
> make SDKROOT=macosx.internal PRODUCT_CONFIGS=j314s 
> EXTRA_CFLAGS='-DKERNEL_STACK_MULTIPLIER=2'
> ```


* RELEASE 커널 설정으로 빌드하려면

    ```text
    make KERNEL_CONFIGS=RELEASE SDKROOT=/path/to/SDK
    ```

### FAT 커널 바이너리 빌드

환경 변수나 make 명령 실행 시 아키텍처를 정의하세요.```text
make ARCH_CONFIGS="X86_64" exporthdrs all

## 커널 캐시 빌드하기

xnu 커널을 테스트하려면, kext와 커널을 단일 부팅 이미지로 연결하는 kernelcache를 빌드해야 합니다.
kernelcache를 빌드하려면 다음 메커니즘을 사용할 수 있습니다:

* `kextd`를 사용한 자동 kernelcache 생성.
  kextd 데몬은 `/System/Library/Extensions` 디렉토리의 변경 사항을 계속 감시합니다.
  따라서 새 커널을 다음과 같이 설정할 수 있습니다.

    ```text
    cp BUILD/obj/DEVELOPMENT/X86_64/kernel.development /System/Library/Kernels/
    touch /System/Library/Extensions
    ps -e | grep kextd
    ```

* `kextcache`를 수동으로 호출하여 새 kernelcache를 빌드합니다.

    ```text
    kextcache -q -z -a x86_64 -l -n -c /var/tmp/kernelcache.test -K /var/tmp/kernel.test /System/Library/Extensions
    ```


## 대상 머신에서 커널 캐시 부팅하기

개발 커널과 iBoot는 부트 인수를 구성하여 테스트 커널을 안전하게 부팅하고, 문제가 발생하면 이전에 사용된 kernelcache로 안전하게 되돌릴 수 있도록 지원합니다.
이러한 설정을 얻기 위한 단계는 다음과 같습니다:

1. `kextcache` 명령어를 사용하여 `/kernelcache.test`로 커널 캐시를 생성합니다.
2. 기존 부트 구성을 대체 파일로 복사합니다.

    ```sh
    cp /Library/Preferences/SystemConfiguration/com.apple.Boot.plist /next_boot.plist
    ```

3. 설정에 맞게 kernelcache와 boot-args를 업데이트합니다.

    ```sh
    plutil -insert "Kernel Cache" -string "kernelcache.test" /next_boot.plist
    plutil -replace "Kernel Flags" -string "debug=0x144 -v kernelsuffix=test " /next_boot.plist
    ```

4. 새 구성을 `/Library/Preferences/SystemConfiguration/`에 복사합니다.

    ```sh
    cp /next_boot.plist /Library/Preferences/SystemConfiguration/boot.plist
    ```

5. 새 구성으로 볼륨을 bless합니다.

    ```text
    sudo -n bless  --mount / --setBoot --nextonly --options "config=boot"
    ```

   `--nextonly` 플래그는 `boot.plist` 구성을 한 번의 부팅에만 사용하도록 지정합니다.
   따라서 커널 패닉이 발생하면 전원을 재부팅하여 원래 커널로 쉽게 복구할 수 있습니다.


## 태그 및 cscope 생성하기

빌드 환경을 설정하고 최상위 디렉토리에서 다음을 실행합니다:

    make tags     # 대소문자 구분 볼륨에서 ctags 및 etags를 빌드하고, 대소문자 미구분 볼륨에서는 ctags만 빌드합니다.
    make TAGS     # etags를 빌드합니다.
    make cscope   # cscope 데이터베이스를 빌드합니다.

## XNU에서 새 헤더 파일 설치하기

XNU는 다음 위치에 헤더 파일을 설치합니다:

    a. $(DSTROOT)/System/Library/Frameworks/Kernel.framework/Headers
    b. $(DSTROOT)/System/Library/Frameworks/Kernel.framework/PrivateHeaders
    c. $(DSTROOT)/usr/include/
    d. $(DSTROOT)/usr/local/include/
    e. $(DSTROOT)/System/DriverKit/usr/include/
    f. $(DSTROOT)/System/Library/Frameworks/IOKit.framework/Headers
    g. $(DSTROOT)/System/Library/Frameworks/IOKit.framework/PrivateHeaders
    h. $(DSTROOT)/System/Library/Frameworks/System.framework/PrivateHeaders

`Kernel.framework`는 커널 확장에서 사용됩니다.\
`System.framework`, `/usr/include` 및 `/usr/local/include`는 사용자 수준 애플리케이션에서 사용됩니다.\
`IOKit.framework`는 IOKit 사용자 공간 클라이언트에서 사용됩니다.\
`/System/DriverKit/usr/include`는 사용자 공간 드라이버에서 사용됩니다.\
프레임워크의 `PrivateHeaders`에 있는 헤더 파일은 **Apple 내부 개발**에만 사용할 수 있습니다.

헤더 파일이 포함된 디렉토리에는 다른 위치에 설치해야 할 파일 목록을 생성하는 Makefile이 있어야 합니다.
디렉토리에 첫 번째 헤더 파일을 추가하는 경우, `xnu/bsd/sys/Makefile`과 유사한 Makefile을 만들어야 합니다.

헤더 파일을 설치하려는 위치에 따라 올바른 파일 목록에 헤더 파일을 추가합니다.
각 파일 목록에서 헤더 파일이 설치되는 기본 위치는 다음과 같습니다:

    a. `DATAFILES` : 사용자 수준에서 헤더 파일을 사용할 수 있도록 하려면 -
       `$(DSTROOT)/usr/include`
       `$(DSTROOT)/System/Library/Frameworks/System.framework/PrivateHeaders`

    b. `DRIVERKIT_DATAFILES` : DriverKit 사용자 공간 드라이버에서 헤더 파일을 사용할 수 있도록 하려면 -
       `$(DSTROOT)/System/DriverKit/usr/include`

    c. `PRIVATE_DATAFILES` : 사용자 수준에서 Apple 내부에서 헤더 파일을 사용할 수 있도록 하려면 -
       `$(DSTROOT)/System/Library/Frameworks/System.framework/PrivateHeaders`

    d. `EMBEDDED_PRIVATE_DATAFILES` : macOS에서는 사용자 수준에서 `EXTRA_DATAFILES`로, 임베디드 OS에서는 `EXTRA_PRIVATE_DATAFILES`로 Apple 내부에서 사용할 수 있도록 하려면 -
       `$(DSTROOT)/usr/include` (`EXTRA_DATAFILES`)
       `$(DSTROOT)/usr/local/include` (`EXTRA_PRIVATE_DATAFILES`)

    e. `KERNELFILES` : 커널 수준에서 헤더 파일을 사용할 수 있도록 하려면 -
       `$(DSTROOT)/System/Library/Frameworks/Kernel.framework/Headers`
       `$(DSTROOT)/System/Library/Frameworks/Kernel.framework/PrivateHeaders`

    f. `PRIVATE_KERNELFILES` : Apple 내부에서 커널 확장을 위해 헤더 파일을 사용할 수 있도록 하려면 -
       `$(DSTROOT)/System/Library/Frameworks/Kernel.framework/PrivateHeaders`

    g. `MODULEMAPFILES` : 사용자 수준에서 모듈 맵 파일을 사용할 수 있도록 하려면 -
       `$(DSTROOT)/usr/include`

    h. `PRIVATE_MODULEMAPFILES` : 사용자 수준에서 Apple 내부에서 모듈 맵 파일을 사용할 수 있도록 하려면 -
       `$(DSTROOT)/usr/local/include`

    i. `LIBCXX_DATAFILES` : 커널 내부 libcxx 클라이언트에서 헤더 파일을 사용할 수 있도록 하려면:
       `$(DSTROOT)/System/Library/Frameworks/Kernel.framework/PrivateHeaders/kernel_sdkroot`

    j. `EXCLAVEKIT_DATAFILES` : Apple 내부 ExclaveKit SDK에서 헤더 파일을 사용할 수 있도록 하려면 -
       `$(DSTROOT)/System/ExclaveKit/usr/include`

    k. `EXCLAVECORE_DATAFILES` : Apple 내부 ExclaveCore SDK에서 헤더 파일을 사용할 수 있도록 하려면 -
       `$(DSTROOT)/System/ExclaveCore/usr/include`

Makefile은 위에 언급된 파일 목록을 빌드 시스템이 헤더 파일을 설치하는 데 사용하는 여러 설치 목록으로 결합합니다.
설치 목록에는 두 가지 유형이 있습니다: 머신 종속적(machine-dependent) 및 머신 독립적(machine-independent)입니다.
이 목록은 빌드 설정에서 각각 `MD` 및 `MI`의 존재로 표시됩니다. 헤더가 아키텍처별인 경우 머신 종속적 설치 목록(예: `INSTALL_MD_LIST`)을 사용해야 합니다. 헤더가 모든 아키텍처에 대해 설치되어야 하는 경우 머신 독립적 설치 목록(예: `INSTALL_MI_LIST`)을 사용해야 합니다.

원하는 설치 목록이 존재하지 않는 경우, 적절한 파일 목록을 추가하여 생성합니다.
기본 설치 목록, 해당 구성 파일 목록 및 기본 위치는 아래에 설명되어 있습니다:

a. `INSTALL_MI_LIST`, `INSTALL_MODULEMAP_MI_LIST` : 사용자 수준의 모든 사용자에게 헤더 및 모듈 맵 파일을 설치합니다.
    위치 -
        $(DSTROOT)/usr/include
    정의 -
        INSTALL_MI_LIST = ${DATAFILES}
        INSTALL_MODULEMAP_MI_LIST = ${MODULEMAPFILES}

b. `INSTALL_DRIVERKIT_MI_LIST` : DriverKit 사용자 공간 드라이버에서 사용할 수 있는 위치에 헤더 파일을 설치합니다.
    위치 -
        $(DSTROOT)/System/DriverKit/usr/include
    정의 -
        INSTALL_DRIVERKIT_MI_LIST = ${DRIVERKIT_DATAFILES}

c.  `INSTALL_MI_LCL_LIST`, `INSTALL_MODULEMAP_MI_LCL_LIST` : 사용자 수준에서 Apple 내부에서 사용할 수 있는 위치에 헤더 및 모듈 맵 파일을 설치합니다.
    위치 -
        $(DSTROOT)/usr/local/include
    정의 -
        INSTALL_MI_LCL_LIST =
        INSTALL_MODULEMAP_MI_LCL_LIST = ${PRIVATE_MODULEMAPFILES}

d. `INSTALL_IF_MI_LIST` : IOKit 사용자 공간 클라이언트의 모든 사용자에게 헤더 파일을 설치합니다.
    위치 -
        $(DSTROOT)/System/Library/Frameworks/IOKit.framework/Headers
    정의 -
        INSTALL_IF_MI_LIST = ${DATAFILES}

e. `INSTALL_IF_MI_LCL_LIST` : IOKit 사용자 공간 클라이언트의 Apple 내부에서 사용할 수 있는 위치에 헤더 파일을 설치합니다.
    위치 -
        $(DSTROOT)/System/Library/Frameworks/IOKit.framework/PrivateHeaders
    정의 -
        INSTALL_IF_MI_LCL_LIST = ${DATAFILES} ${PRIVATE_DATAFILES}

f.  `INSTALL_SF_MI_LCL_LIST` : 사용자 수준에서 Apple 내부에서 사용할 수 있는 위치에 헤더 파일을 설치합니다.
    위치 -
        $(DSTROOT)/System/Library/Frameworks/System.framework/PrivateHeaders
    정의 -
        INSTALL_SF_MI_LCL_LIST = ${DATAFILES} ${PRIVATE_DATAFILES}

g. `INSTALL_KF_MI_LIST` : 커널 확장의 모든 사용자에게 헤더 파일을 설치합니다.
    위치 -
        $(DSTROOT)/System/Library/Frameworks/Kernel.framework/Headers
    정의 -
        INSTALL_KF_MI_LIST = ${KERNELFILES}

h. `INSTALL_KF_MI_LCL_LIST` : 커널 확장의 Apple 내부에서 사용할 수 있는 위치에 헤더 파일을 설치합니다.
    위치 -
        $(DSTROOT)/System/Library/Frameworks/Kernel.framework/PrivateHeaders
    정의 -
        INSTALL_KF_MI_LCL_LIST = ${KERNELFILES} ${PRIVATE_KERNELFILES}

i. `EXPORT_MI_LIST` : 컴파일을 위해서만 xnu의 모든 부분(bsd/, osfmk/ 등)에 헤더 파일을 내보냅니다. SDK에는 아무것도 설치하지 않습니다.
    정의 -
        EXPORT_MI_LIST = ${KERNELFILES} ${PRIVATE_KERNELFILES}

j. `INSTALL_KF_LIBCXX_MI_LIST` : 커널 내부 libc++ 지원을 위해 헤더 파일을 설치합니다.
    위치 -
        $(DSTROOT)/System/Library/Frameworks/Kernel.framework/PrivateHeaders/kernel_sdkroot
    정의 -
        INSTALL_KF_LIBCXX_MI_LIST = ${LIBCXX_DATAFILES}

k. `INSTALL_EXCLAVEKIT_MI_LIST` : ExclaveKit의 Apple 내부에서 사용할 수 있는 위치에 헤더 파일을 설치합니다.
    위치 -
        $(DSTROOT)/System/ExclaveKit/usr/include
    정의 -
        INSTALL_EXCLAVEKIT_MI_LIST = ${EXCLAVEKIT_DATAFILES}

l. `INSTALL_EXCLAVECORE_MI_LIST` : ExclaveCore의 Apple 내부에서 사용할 수 있는 위치에 헤더 파일을 설치합니다.
    위치 -
        $(DSTROOT)/System/ExclaveCore/usr/include
    정의 -
        INSTALL_EXCLAVECORE_MI_LIST = ${EXCLAVECORE_DATAFILES}

(1)에 설명된 경로의 하위 디렉토리에 헤더 파일을 설치하려면 `INSTALL_MI_DIR` 및 `EXPORT_MI_DIR` 두 변수를 사용하여 디렉토리 이름을 다음과 같이 지정하십시오.```text
INSTALL_MI_DIR = dirname
EXPORT_MI_DIR = dirname

단일 헤더 파일은 위에서 언급한 단계를 사용하여 서로 다른 위치에 존재할 수 있습니다. 그러나 헤더 파일의 모든 코드를 모든 위치에서 사용할 수 있도록 하는 것이 바람직하지 않을 수 있습니다. 예를 들어, 커널 수준에서만 함수를 내보내고 사용자 수준에서는 내보내지 않을 수 있습니다.

C 언어의 전처리기 지시문(#ifdef, #endif, #ifndef)을 사용하여 헤더 파일이 설치되기 전에 생성되는 텍스트를 제어할 수 있습니다. 커널은 조건부 매크로가 TRUE인 경우에만 코드를 포함하고, FALSE 조건의 코드는 헤더 파일에서 제거합니다.

사전 정의된 일부 매크로와 해당 설명은 다음과 같습니다.

1. `PRIVATE` : 정의된 경우, 포함된 정의는 시스템 비공개 인터페이스(System Private Interfaces)로 간주됩니다. 이는 xnu 내에서 볼 수 있으며, AppleInternal "PrivateHeaders" 섹션 내의 System 및 Kernel 프레임워크에 설치된 사용자/커널 헤더에 노출됩니다.
2. `KERNEL_PRIVATE` : 정의된 경우, 포함된 코드는 xnu 커널 및 Apple 내부 커널 확장에서 모두 사용할 수 있으며 사용자 헤더에서 생략됩니다.
3. `BSD_KERNEL_PRIVATE` : 정의된 경우, 포함된 코드는 xnu/bsd 모듈 내에서만 독점적으로 표시됩니다.
4. `MACH_KERNEL_PRIVATE` : 정의된 경우, 포함된 코드는 xnu/osfmk 모듈 내에서만 독점적으로 표시됩니다.
5. `XNU_KERNEL_PRIVATE` : 정의된 경우, 포함된 코드는 xnu 내에서만 독점적으로 표시됩니다.
6. `KERNEL` : 정의된 경우, 포함된 코드는 xnu 및 커널 확장 내에서 사용할 수 있으며 사용자 수준 헤더 파일에서는 표시되지 않습니다. 다음 경로에 설치된 헤더 파일만 해당 코드를 포함합니다.

    ```text
    $(DSTROOT)/System/Library/Frameworks/Kernel.framework/Headers
    $(DSTROOT)/System/Library/Frameworks/Kernel.framework/PrivateHeaders
    ```

7. `DRIVERKIT` : 정의된 경우, 포함된 코드는 사용자 공간 드라이버에서 사용하는 DriverKit SDK 헤더에서만 독점적으로 표시됩니다.
8. `EXCLAVEKIT` : 정의된 경우, 포함된 코드는 ExclaveKit SDK 헤더에서만 독점적으로 표시됩니다.
9. `EXCLAVECORE` : 정의된 경우, 포함된 코드는 ExclaveCore SDK 헤더에서만 독점적으로 표시됩니다.
10. `MODULES_SUPPORTED` : 정의된 경우, 포함된 코드는 모듈/Swift를 지원하는 위치(즉, System 또는 Kernel 프레임워크가 아님)에서만 독점적으로 표시됩니다.

## VM 헤더 파일 이름 규칙

VM 헤더는 다음 명명 규칙을 따릅니다:
* `*_internal.h` 헤더에는 VM 코드에서만 사용하기 위한 VM 하위 시스템의 구성 요소가 포함됩니다.
* `*_xnu.h` 헤더에는 다른 xnu 코드에서만 사용하기 위한 VM 하위 시스템의 구성 요소가 포함됩니다.
* `*.h` 헤더에는 kext로 내보내는 VM 하위 시스템의 구성 요소가 포함됩니다.
* `vm_iokit.h` 헤더에는 iokit 하위 시스템으로 내보내는 VM 하위 시스템의 구성 요소가 포함됩니다.
* `vm_ubc.h` 헤더에는 ubc 하위 시스템으로 내보내는 VM 하위 시스템의 구성 요소가 포함됩니다.

## 모듈 맵 파일 이름 규칙

간단한 경우, `usr/include` 또는 `usr/local/include`의 하위 디렉터리는 독립형 모듈로 나타낼 수 있습니다. 이러한 경우 `INSTALL_MODULEMAP_MI_DIR`을 `INSTALL_MI_DIR`로 설정하고 해당 위치에 `module.modulemap` 파일을 설치합니다. `module.modulemap`은 `usr/local/include`의 비공개 모듈에도 사용됩니다. `module.private.modulemap`은 사용되지 않습니다. 주의: 간단한 경우를 유지하려면 모듈 이름이 디렉터리 이름과 정확히 같아야 합니다. 그렇지 않은 경우 다음 방법을 적용해야 합니다.

`xnu`는 CoreOSModuleMaps에 정의된 모듈에 기여하기 위해 `usr/include/module.modulemap` 및 `usr/local/include/module.modulemap`에서 가져온 모듈 맵 파일을 설치합니다. `xnu` 모듈 맵 파일의 명명 규칙은 다음과 같습니다.

a. 이상적으로 모듈 맵 파일은 전체 디렉터리를 다룹니다. `usr/include/a/b/c`를 다루는 모듈 맵 파일은 `a_b_c.modulemap`으로 이름이 지정됩니다. `usr/local/include/a/b/c`는 `a_b_c_private.modulemap`이 됩니다.
b. 일부 헤더는 특별하며 자체 모듈이 필요합니다. 이 경우 모듈 맵 파일은 정의하는 모듈의 이름을 따서 명명됩니다. `One.Two.Three` 모듈을 정의하는 모듈 맵 파일은 `one_two_three.modulemap`으로 이름이 지정됩니다.

## 조건부 컴파일

`xnu`는 코드를 조건부로 컴파일하기 위해 다음과 같은 메커니즘을 제공합니다.

1. *CPU 특성* 보호 중인 코드가 대상이 되는 CPU 아키텍처에 따라서만 달라지는 특정 특성을 가진 경우 이 옵션을 사용하세요. 아키텍처의 기능(예: `__LP64__`, `__LITTLE_ENDIAN__` 등)을 확인하는 것이 좋습니다.
2. *새로운 기능* 보호 중인 코드가 함께 구성되어 하나의 기능을 구현하는 경우 `config/MASTER`에 새 기능을 정의하고 결과 `CONFIG` 전처리기 토큰을 사용해야 합니다(예: `config_virtual_memory`라는 기능의 경우 `#if CONFIG_VIRTUAL_MEMORY` 확인). 이 방식은 기존 기능을 기능 스위치만 변경하여 다른 플랫폼으로 가져올 수 있도록 보장합니다.
3. *기존 기능* 코드가 기존 기능과 강하게 연결된 경우 기존 기능을 사용할 수 있습니다(예: 코드가 신뢰할 수 있는 커널과만 관련된 새로운 기능을 구현하고 신뢰할 수 있는 커널의 정의/이해를 업데이트하는 경우 `SECURE_KERNEL` 사용).

대상 플랫폼을 기준으로 컴파일하지 않는 것이 좋습니다. `xnu`는 `TargetConditionals.h`의 플랫폼 매크로(`TARGET_OS_OSX`, `TARGET_OS_IOS` 등)를 정의하지 않습니다.

## XNU 디버깅

기본적으로 커널은 패닉이 발생하면 재부팅됩니다. 이 동작은 `debug` 부트 인수로 재정의할 수 있습니다. `debug=0x14e`는 패닉 시 디버거 연결을 기다리게 합니다. 연결된 시스템에서 디버그할 수 있도록 커널을 부팅하려면 적절한 `ifconfig` 인터페이스로 `kdp_match_name` 부트 인수를 재정의하세요. 이더넷, 썬더볼트 및 직렬 디버깅이 하드웨어에 따라 지원됩니다.

LLDB를 사용하여 커널을 디버그하세요:```text
xcrun -sdk macosx lldb <path-to-unstripped-kernel>
(lldb) gdb-remote [<host-ip>:]<port>

`tools/lldbmacros` 이 명령어들의 소스 코드를 포함하고 있습니다.
해당 디렉토리의 README에서 사용법을 확인하거나, 내장 LLDB 도움말을 사용하십시오:```text
(lldb) help showcurrentstacks