jackcartersmith/gse
1
0
Fork 0
Code Issues Pull Requests Actions Releases Activity

Compare commits

base: jackcartersmith:dev
Branches Tags
jackcartersmith:dev
jackcartersmith:third-party/build/win
jackcartersmith:third-party/deps/win
jackcartersmith:third-party/deps/linux
jackcartersmith:third-party/deps/common
jackcartersmith:third-party/common/win
jackcartersmith:third-party/common/linux
jackcartersmith:third-party/build/linux
jackcartersmith:2024_10_21
jackcartersmith:2024_10_14
jackcartersmith:2024_10_07-overlay_fix_test_03
jackcartersmith:2024_10_07-overlay_fix_test_02
jackcartersmith:2024_10_07-overlay_fix_test_01
jackcartersmith:2024_10_07
jackcartersmith:2024_09_27
jackcartersmith:2024_8_25
jackcartersmith:2024_8_19
jackcartersmith:2024_8_4
..
compare: jackcartersmith:third-party/deps/linux
Branches Tags
jackcartersmith:dev
jackcartersmith:third-party/build/win
jackcartersmith:third-party/deps/win
jackcartersmith:third-party/deps/linux
jackcartersmith:third-party/deps/common
jackcartersmith:third-party/common/win
jackcartersmith:third-party/common/linux
jackcartersmith:third-party/build/linux
jackcartersmith:2024_10_21
jackcartersmith:2024_10_14
jackcartersmith:2024_10_07-overlay_fix_test_03
jackcartersmith:2024_10_07-overlay_fix_test_02
jackcartersmith:2024_10_07-overlay_fix_test_01
jackcartersmith:2024_10_07
jackcartersmith:2024_09_27
jackcartersmith:2024_8_25
jackcartersmith:2024_8_19
jackcartersmith:2024_8_4

No commits in common. "dev" and "third-party/deps/linux" have entirely different histories.
dev ... third-part

4190 changed files with 237100 additions and 319746 deletions
Show Stats Expand all files Collapse all files

20
.editorconfig
View File

@ -1,20 +0,0 @@
root = true
[*]
indent_style = space
indent_size = 2
end_of_line = lf
charset = utf-8
trim_trailing_whitespace = true
insert_final_newline = true
max_line_length = 120
[*.py]
indent_size = 4
[*.h]
indent_size = 4
[*.cpp]
indent_size = 4

123
.github/workflows/emu-build-all-linux.yml vendored
View File

@ -1,123 +0,0 @@
name: "Build emu (Linux)"
on:
workflow_call:
# needed since it allows this to become a reusable workflow
workflow_dispatch:
# allows manual trigger
permissions:
contents: "write"
env:
PREMAKE_ACTION: "gmake2"
DEPS_CACHE_KEY: "emu-deps-linux"
DEPS_CACHE_DIR: "build/deps/linux"
PACKAGE_BASE_DIR: "build/package/linux"
THIRD_PARTY_BASE_DIR: "third-party"
jobs:
deps:
name: "Restore or build deps"
if: ${{ !cancelled() }}
uses: "./.github/workflows/emu-deps-linux.yml"
builds-matrix-linux:
name: "build"
needs: ["deps"]
runs-on: "ubuntu-20.04"
if: ${{ !cancelled() }}
continue-on-error: true
strategy:
fail-fast: false
matrix:
prj: [
# regular api
"api_regular",
"steamclient_regular",
# api + client (experimental)
"api_experimental",
"steamclient_experimental",
# tools
"tool_lobby_connect",
"tool_generate_interfaces",
]
arch: ["x64", "x32"]
cfg: ["debug", "release"]
steps:
# clone branch
- name: "Checkout branch"
uses: actions/checkout@v4
# deps
- name: "Restore deps"
id: "emu-deps-cache-step"
uses: actions/cache@v4
with:
key: "${{ env.DEPS_CACHE_KEY }}-${{ env.PREMAKE_ACTION }}"
path: "${{ env.DEPS_CACHE_DIR }}/${{ env.PREMAKE_ACTION }}"
# extra helpers/tools, these are not built inside the deps build dir
- name: "Clone third-party build helpers (common/linux)"
uses: actions/checkout@v4
with:
ref: "third-party/common/linux"
path: "${{env.THIRD_PARTY_BASE_DIR}}/common/linux"
- name: "Clone third-party build helpers (build/linux)"
uses: actions/checkout@v4
with:
ref: "third-party/build/linux"
path: "${{env.THIRD_PARTY_BASE_DIR}}/build/linux"
# fix folder permissions! not sure why this fails
# nested subdirs "build/linux/release" cause permission problems
- name: "Give all permissions to repo folder"
shell: "bash"
working-directory: "${{ github.workspace }}"
run: sudo chmod -R 777 "${{ github.workspace }}"
# generate project files
- name: "Generate project files"
shell: "bash"
working-directory: "${{ github.workspace }}"
run: |
sudo chmod 777 ./${{env.THIRD_PARTY_BASE_DIR}}/common/linux/premake/premake5
./${{env.THIRD_PARTY_BASE_DIR}}/common/linux/premake/premake5 --file=premake5.lua --genproto --emubuild=${{ github.sha }} --os=linux gmake2
# mandatory Linux packages
- name: "Install required packages"
shell: "bash"
run: |
sudo apt update -y
sudo apt install -y coreutils # echo, printf, etc...
sudo apt install -y build-essential
sudo apt install -y gcc-multilib # needed for 32-bit builds
sudo apt install -y g++-multilib
# sudo apt install -y clang
sudo apt install -y libglx-dev # needed for overlay build (header files such as GL/glx.h)
sudo apt install -y libgl-dev # needed for overlay build (header files such as GL/gl.h)
# sudo apt install -y binutils # (optional) contains the tool 'readelf' mainly, and other usefull binary stuff
# build target
- name: "Build target"
shell: "bash"
working-directory: "${{ github.workspace }}/build/project/gmake2/linux"
run: |
echo "dry run..."
make -n -j 2 config=${{ matrix.cfg }}_${{ matrix.arch }} ${{ matrix.prj }}
echo "actual run..."
make -j 2 config=${{ matrix.cfg }}_${{ matrix.arch }} ${{ matrix.prj }}
# upload artifact/package to github Actions
- name: "Upload target package"
uses: actions/upload-artifact@v4
with:
name: "emu-linux-${{ matrix.prj }}-${{ matrix.cfg }}-${{ matrix.arch }}-${{ github.sha }}"
path: "build/linux"
if-no-files-found: "error"
compression-level: 9
retention-days: 1

114
.github/workflows/emu-build-all-win.yml vendored
View File

@ -1,114 +0,0 @@
name: "Build emu (Windows)"
on:
workflow_call:
# needed since it allows this to become a reusable workflow
workflow_dispatch:
# allows manual trigger
permissions:
contents: "write"
env:
PREMAKE_ACTION: "vs2022"
DEPS_CACHE_KEY: "emu-deps-win"
DEPS_CACHE_DIR: "build/deps/win"
THIRD_PARTY_BASE_DIR: "third-party"
jobs:
deps:
name: "Restore or build deps"
if: ${{ !cancelled() }}
uses: "./.github/workflows/emu-deps-win.yml"
builds-matrix-win:
name: "build"
needs: ["deps"]
runs-on: "windows-2022"
if: ${{ !cancelled() }}
continue-on-error: true
strategy:
fail-fast: false
matrix:
prj: [
# regular api
"api_regular",
# (experimental) api + client
"api_experimental",
"steamclient_experimental_stub",
# client (experimental) + loader + extra dll + gameoverlaylib
"steamclient_experimental",
"steamclient_experimental_loader",
"steamclient_experimental_extra",
"lib_game_overlay_renderer",
# tools
"tool_lobby_connect",
"tool_generate_interfaces",
]
arch: ["x64", "Win32"]
cfg: ["debug", "release"]
steps:
# on Windows Git will auto change line ending to CRLF, not preferable
- name: "Ensure LF line ending"
shell: "cmd"
working-directory: "${{ github.workspace }}"
run: |
git config --local core.autocrlf false
git config --system core.autocrlf false
git config --global core.autocrlf false
# ensure we have msbuild
- name: "Add MSBuild to PATH"
uses: microsoft/setup-msbuild@v2
# clone branch
- name: "Checkout branch"
uses: actions/checkout@v4
# deps
- name: "Restore deps"
id: "emu-deps-cache-step"
uses: actions/cache@v4
with:
key: "${{ env.DEPS_CACHE_KEY }}-${{ env.PREMAKE_ACTION }}"
path: "${{ env.DEPS_CACHE_DIR }}/${{ env.PREMAKE_ACTION }}"
# extra helpers/tools, these are not built inside the deps build dir
- name: "Clone third-party build helpers (common/win)"
uses: actions/checkout@v4
with:
ref: "third-party/common/win"
path: "${{env.THIRD_PARTY_BASE_DIR}}/common/win"
- name: "Clone third-party deps (build/win)"
uses: actions/checkout@v4
with:
ref: "third-party/build/win"
path: "${{env.THIRD_PARTY_BASE_DIR}}/build/win"
# generate project files
- name: "Generate project files"
shell: "cmd"
working-directory: "${{ github.workspace }}"
run: |
"${{env.THIRD_PARTY_BASE_DIR}}\common\win\premake\premake5.exe" --file=premake5.lua --genproto --emubuild=${{ github.sha }} --dosstub --winrsrc --winsign --os=windows vs2022
# build target
- name: "Build target"
shell: "cmd"
working-directory: "${{ github.workspace }}/build/project/vs2022/win"
run: |
msbuild /nologo /target:${{ matrix.prj }} /m:2 /v:n /p:Configuration=${{ matrix.cfg }},Platform=${{ matrix.arch }} gbe.sln
# upload artifact/package to github Actions
- name: "Upload target package"
uses: actions/upload-artifact@v4
with:
name: "emu-win-${{ matrix.prj }}-${{ matrix.cfg }}-${{ matrix.arch }}-${{ github.sha }}"
path: "build/win"
if-no-files-found: "error"
compression-level: 9
retention-days: 1

88
.github/workflows/emu-deps-linux.yml vendored
View File

@ -1,88 +0,0 @@
name: "Emu third-party dependencies (Linux)"
on:
workflow_call:
# needed since it allows this to become a reusable workflow
workflow_dispatch:
# allows manual trigger
permissions:
contents: "write"
env:
PREMAKE_ACTION: "gmake2"
DEPS_CACHE_KEY: "emu-deps-linux"
DEPS_CACHE_DIR: "build/deps/linux"
PACKAGE_BASE_DIR: "build/package/linux"
THIRD_PARTY_BASE_DIR: "third-party"
jobs:
deps-build:
runs-on: "ubuntu-20.04"
if: ${{ !cancelled() }}
steps:
- name: "Lookup cache for deps"
id: "emu-deps-cache-step"
uses: actions/cache@v4
with:
key: "${{ env.DEPS_CACHE_KEY }}-${{ env.PREMAKE_ACTION }}"
path: "${{ env.DEPS_CACHE_DIR }}/${{ env.PREMAKE_ACTION }}"
# we need branch because it has build scripts
- name: "Checkout branch"
if: steps.emu-deps-cache-step.outputs.cache-hit != 'true'
uses: actions/checkout@v4
- name: "Clone third-party deps (common/linux)"
if: steps.emu-deps-cache-step.outputs.cache-hit != 'true'
uses: actions/checkout@v4
with:
ref: "third-party/common/linux"
path: "${{env.THIRD_PARTY_BASE_DIR}}/common/linux"
- name: "Clone third-party deps (deps/linux)"
if: steps.emu-deps-cache-step.outputs.cache-hit != 'true'
uses: actions/checkout@v4
with:
ref: "third-party/deps/linux"
path: "${{env.THIRD_PARTY_BASE_DIR}}/deps/linux"
- name: "Clone third-party deps (deps/common)"
if: steps.emu-deps-cache-step.outputs.cache-hit != 'true'
uses: actions/checkout@v4
with:
ref: "third-party/deps/common"
path: "${{env.THIRD_PARTY_BASE_DIR}}/deps/common"
# fix folder permissions! not sure why this fails
# nested subdirs "build/linux/release" cause permission problems
- name: "Give all permissions to repo folder"
if: steps.emu-deps-cache-step.outputs.cache-hit != 'true'
shell: "bash"
working-directory: "${{ github.workspace }}"
run: sudo chmod -R 777 "${{ github.workspace }}"
# mandatory Linux packages
- name: "Install required packages"
shell: "bash"
run: |
sudo apt update -y
sudo apt install -y coreutils # echo, printf, etc...
sudo apt install -y build-essential
sudo apt install -y gcc-multilib # needed for 32-bit builds
sudo apt install -y g++-multilib
# sudo apt install -y clang
sudo apt install -y libglx-dev # needed for overlay build (header files such as GL/glx.h)
sudo apt install -y libgl-dev # needed for overlay build (header files such as GL/gl.h)
# sudo apt install -y binutils # (optional) contains the tool 'readelf' mainly, and other usefull binary stuff
- name: "Build deps"
if: steps.emu-deps-cache-step.outputs.cache-hit != 'true'
shell: "bash"
working-directory: "${{ github.workspace }}"
run: |
export CMAKE_GENERATOR="Unix Makefiles"
sudo chmod 777 ./${{env.THIRD_PARTY_BASE_DIR}}/common/linux/premake/premake5
./${{env.THIRD_PARTY_BASE_DIR}}/common/linux/premake/premake5 --file=premake5-deps.lua --64-build --32-build --all-ext --all-build --j=2 --verbose --clean --os=linux gmake2

82
.github/workflows/emu-deps-win.yml vendored
View File

@ -1,82 +0,0 @@
name: "Emu third-party dependencies (Windows)"
on:
workflow_call:
# needed since it allows this to become a reusable workflow
workflow_dispatch:
# allows manual trigger
permissions:
contents: "write"
env:
PREMAKE_ACTION: "vs2022"
DEPS_CACHE_KEY: "emu-deps-win"
DEPS_CACHE_DIR: "build/deps/win"
PACKAGE_BASE_DIR: "build/package/win"
THIRD_PARTY_BASE_DIR: "third-party"
jobs:
deps-build:
runs-on: "windows-2022"
if: ${{ !cancelled() }}
steps:
# on Windows Git will auto change line ending to CRLF, not preferable
- name: "Ensure LF line ending"
shell: "cmd"
working-directory: ${{ github.workspace }}
run: |
git config --local core.autocrlf false
git config --system core.autocrlf false
git config --global core.autocrlf false
- name: "Lookup cache for deps"
id: "emu-deps-cache-step"
uses: actions/cache@v4
with:
key: "${{ env.DEPS_CACHE_KEY }}-${{ env.PREMAKE_ACTION }}"
path: "${{ env.DEPS_CACHE_DIR }}/${{ env.PREMAKE_ACTION }}"
lookup-only: true # don't restore cache if found
# we need branch because it has build scripts
- name: "Checkout branch"
if: steps.emu-deps-cache-step.outputs.cache-hit != 'true'
uses: actions/checkout@v4
- name: "Clone third-party deps (common/win)"
if: steps.emu-deps-cache-step.outputs.cache-hit != 'true'
uses: actions/checkout@v4
with:
ref: "third-party/common/win"
path: "${{env.THIRD_PARTY_BASE_DIR}}/common/win"
- name: "Clone third-party deps (deps/win)"
if: steps.emu-deps-cache-step.outputs.cache-hit != 'true'
uses: actions/checkout@v4
with:
ref: "third-party/deps/win"
path: "${{env.THIRD_PARTY_BASE_DIR}}/deps/win"
- name: "Clone third-party deps (deps/common)"
if: steps.emu-deps-cache-step.outputs.cache-hit != 'true'
uses: actions/checkout@v4
with:
ref: "third-party/deps/common"
path: "${{env.THIRD_PARTY_BASE_DIR}}/deps/common"
- name: "Clone third-party deps (common/win)"
if: steps.emu-deps-cache-step.outputs.cache-hit != 'true'
uses: actions/checkout@v4
with:
ref: "third-party/common/win"
path: "${{env.THIRD_PARTY_BASE_DIR}}/common/win"
- name: "Build deps"
if: steps.emu-deps-cache-step.outputs.cache-hit != 'true'
shell: "cmd"
working-directory: "${{ github.workspace }}"
run: |
set "CMAKE_GENERATOR=Visual Studio 17 2022"
"${{env.THIRD_PARTY_BASE_DIR}}\common\win\premake\premake5.exe" --file=premake5-deps.lua --64-build --32-build --all-ext --all-build --j=2 --verbose --clean --os=windows vs2022

30
.github/workflows/emu-pull-request.yml vendored
View File

@ -1,30 +0,0 @@
name: "Emu PR"
on:
pull_request:
branches: ["dev"]
paths-ignore:
- "**/*.md"
- "dev.notes/**"
- "post_build/**"
- "z_original_repo_files/**"
- "sdk/*.txt"
- "LICENSE"
# tools
- "tools/generate_emu_config/**"
- "tools/migrate_gse/**"
- "tools/steamclient_loader/linux/**" # these are just scripts, not built
permissions:
contents: "write"
jobs:
emu-win-all:
name: "win"
if: ${{ !cancelled() }}
uses: "./.github/workflows/emu-build-all-win.yml"
emu-linux-all:
name: "linux"
if: ${{ !cancelled() }}
uses: "./.github/workflows/emu-build-all-linux.yml"

52
.github/workflows/gen_emu_config-build-linux.yml vendored
View File

@ -1,52 +0,0 @@
name: "Build gen_emu_config script (Linux)"
on:
workflow_call:
# needed since it allows this to become a reusable workflow
workflow_dispatch:
# allows manual trigger
permissions:
contents: "write"
env:
ARTIFACT_NAME: "generate_emu_config-linux-${{ github.sha }}"
SCRIPT_BASE_DIR: "tools/generate_emu_config"
PACKAGE_BASE_DIR: "tools/generate_emu_config/bin/linux"
jobs:
build:
runs-on: "ubuntu-20.04"
steps:
- name: "Checkout branch"
uses: actions/checkout@v4
# env
- name: "Install env"
shell: "bash"
working-directory: "${{ env.SCRIPT_BASE_DIR }}"
run: sudo chmod 777 recreate_venv_linux.sh && sudo ./recreate_venv_linux.sh
# fix folder permissions! not sure why this fails
# nested subdirs "build/linux/release" cause permission problems
- name: "Give all permissions to repo folder"
shell: "bash"
working-directory: "${{ github.workspace }}"
run: sudo chmod -R 777 "${{ github.workspace }}"
# build
- name: "Rebuild"
shell: "bash"
working-directory: "${{ env.SCRIPT_BASE_DIR }}"
run: sudo chmod 777 rebuild_linux.sh && ./rebuild_linux.sh
# upload artifact
- name: "Upload build package"
uses: actions/upload-artifact@v4
with:
name: "${{ env.ARTIFACT_NAME }}"
path: "${{ env.PACKAGE_BASE_DIR }}/"
if-no-files-found: "error"
compression-level: 9
retention-days: 1

83
.github/workflows/gen_emu_config-build-win.yml vendored
View File

@ -1,83 +0,0 @@
name: "Build gen_emu_config script (Windows)"
on:
workflow_call:
# needed since it allows this to become a reusable workflow
workflow_dispatch:
# allows manual trigger
permissions:
contents: "write"
env:
ARTIFACT_NAME: "generate_emu_config-win-${{ github.sha }}"
SCRIPT_BASE_DIR: "tools/generate_emu_config"
PACKAGE_BASE_DIR: "tools/generate_emu_config/bin/win"
THIRD_PARTY_BASE_DIR: "third-party"
jobs:
build:
runs-on: "windows-2022"
steps:
- name: "Set up Python"
uses: actions/setup-python@v5
with:
python-version: "3.12"
### on Windows Git will auto change line ending to CRLF, not preferable
- name: "Ensure LF line ending"
shell: "cmd"
working-directory: "${{ github.workspace }}"
run: |
git config --local core.autocrlf false
git config --system core.autocrlf false
git config --global core.autocrlf false
- name: "Checkout branch"
uses: actions/checkout@v4
## extra helpers/tools, these are not built inside the deps build dir
- name: "Clone third-party deps (build/win)"
uses: actions/checkout@v4
with:
ref: "third-party/build/win"
path: "${{env.THIRD_PARTY_BASE_DIR}}/build/win"
## clone this for 7za.exe
- name: "Clone third-party deps (deps/win)"
uses: actions/checkout@v4
with:
ref: "third-party/deps/win"
path: "${{env.THIRD_PARTY_BASE_DIR}}/deps/win"
# download artifacts
- name: "Download emu build artifacts (Win)"
uses: actions/download-artifact@v4
with:
path: "build/win"
pattern: "emu-win-*"
merge-multiple: true
# env
- name: "Install env"
shell: "cmd"
working-directory: "${{ env.SCRIPT_BASE_DIR }}"
run: recreate_venv_win.bat
# build
- name: "Rebuild"
shell: "cmd"
working-directory: "${{ env.SCRIPT_BASE_DIR }}"
run: rebuild_win.bat
# upload artifact
- name: "Upload build package"
uses: actions/upload-artifact@v4
with:
name: "${{ env.ARTIFACT_NAME }}"
path: "${{ env.PACKAGE_BASE_DIR }}/"
if-no-files-found: "error"
compression-level: 9
retention-days: 1

22
.github/workflows/gen_emu_config-pull-request.yml vendored
View File

@ -1,22 +0,0 @@
name: "Gen emu cfg PR"
on:
pull_request:
branches: ["dev"]
paths:
- "!**/*.md"
- "tools/generate_emu_config/**"
permissions:
contents: "write"
jobs:
script-win:
name: "Gen emu config win"
if: ${{ !cancelled() }}
uses: "./.github/workflows/gen_emu_config-build-win.yml"
script-linux:
name: "Gen emu config linux"
if: ${{ !cancelled() }}
uses: "./.github/workflows/gen_emu_config-build-linux.yml"

52
.github/workflows/migrate_gse-build-linux.yml vendored
View File

@ -1,52 +0,0 @@
name: "Build migrate_gse script (Linux)"
on:
workflow_call:
# needed since it allows this to become a reusable workflow
workflow_dispatch:
# allows manual trigger
permissions:
contents: "write"
env:
ARTIFACT_NAME: "migrate_gse-linux-${{ github.sha }}"
SCRIPT_BASE_DIR: "tools/migrate_gse"
PACKAGE_BASE_DIR: "tools/migrate_gse/bin/linux"
jobs:
build:
runs-on: "ubuntu-20.04"
steps:
- name: "Checkout branch"
uses: actions/checkout@v4
# fix folder permissions! not sure why this fails
# nested subdirs "build/linux/release" cause permission problems
- name: "Give all permissions to repo folder"
shell: "bash"
working-directory: "${{ github.workspace }}"
run: sudo chmod -R 777 "${{ github.workspace }}"
# env
- name: "Install env"
shell: "bash"
working-directory: "${{ env.SCRIPT_BASE_DIR }}"
run: sudo chmod 777 recreate_venv_linux.sh && sudo ./recreate_venv_linux.sh
# build
- name: "Rebuild"
shell: "bash"
working-directory: "${{ env.SCRIPT_BASE_DIR }}"
run: sudo chmod 777 rebuild_linux.sh && ./rebuild_linux.sh
# upload artifact
- name: "Upload build package"
uses: actions/upload-artifact@v4
with:
name: "${{ env.ARTIFACT_NAME }}"
path: "${{ env.PACKAGE_BASE_DIR }}/"
if-no-files-found: "error"
compression-level: 9
retention-days: 1

83
.github/workflows/migrate_gse-build-win.yml vendored
View File

@ -1,83 +0,0 @@
name: "Build migrate_gse script (Windows)"
on:
workflow_call:
# needed since it allows this to become a reusable workflow
workflow_dispatch:
# allows manual trigger
permissions:
contents: "write"
env:
ARTIFACT_NAME: "migrate_gse-win-${{ github.sha }}"
SCRIPT_BASE_DIR: "tools/migrate_gse"
PACKAGE_BASE_DIR: "tools/migrate_gse/bin/win"
THIRD_PARTY_BASE_DIR: "third-party"
jobs:
build:
runs-on: "windows-2022"
steps:
- name: "Set up Python 3.12"
uses: actions/setup-python@v5
with:
python-version: "3.12"
# on Windows Git will auto change line ending to CRLF, not preferable
- name: "Ensure LF line ending"
shell: "cmd"
working-directory: "${{ github.workspace }}"
run: |
git config --local core.autocrlf false
git config --system core.autocrlf false
git config --global core.autocrlf false
- name: "Checkout branch"
uses: actions/checkout@v4
# extra helpers/tools, these are not built inside the deps build dir
- name: "Clone third-party deps (build/win)"
uses: actions/checkout@v4
with:
ref: "third-party/build/win"
path: "${{env.THIRD_PARTY_BASE_DIR}}/build/win"
## clone this for 7za.exe
- name: "Clone third-party deps (deps/win)"
uses: actions/checkout@v4
with:
ref: "third-party/deps/win"
path: "${{env.THIRD_PARTY_BASE_DIR}}/deps/win"
# download artifacts
- name: "Download emu build artifacts (Win)"
uses: actions/download-artifact@v4
with:
path: "build/win"
pattern: "emu-win-*"
merge-multiple: true
# env
- name: "Install env"
shell: cmd
working-directory: "${{ env.SCRIPT_BASE_DIR }}"
run: recreate_venv_win.bat
# build
- name: "Rebuild"
shell: cmd
working-directory: "${{ env.SCRIPT_BASE_DIR }}"
run: rebuild_win.bat
# upload artifact
- name: "Upload build package"
uses: actions/upload-artifact@v4
with:
name: "${{ env.ARTIFACT_NAME }}"
path: "${{ env.PACKAGE_BASE_DIR }}/"
if-no-files-found: "error"
compression-level: 9
retention-days: 1

22
.github/workflows/migrate_gse-pull-request.yml vendored
View File

@ -1,22 +0,0 @@
name: "Migrate GSE PR"
on:
pull_request:
branches: ["dev"]
paths:
- "!**/*.md"
- "tools/migrate_gse/**"
permissions:
contents: "write"
jobs:
script-win:
name: "Migrate GSE win"
if: ${{ !cancelled() }}
uses: "./.github/workflows/migrate_gse-build-win.yml"
script-linux:
name: "Migrate GSE linux"
if: ${{ !cancelled() }}
uses: "./.github/workflows/migrate_gse-build-linux.yml"

415
.github/workflows/release.yml vendored
View File

@ -1,415 +0,0 @@
name: "Prepare release"
on:
push:
tags:
- "release-*"
workflow_dispatch:
# allows manual trigger
permissions:
contents: "write"
env:
THIRD_PARTY_BASE_DIR: "third-party"
jobs:
emu-win-all:
name: "Emu win all"
if: ${{ !cancelled() }}
uses: "./.github/workflows/emu-build-all-win.yml"
emu-win-prep:
needs: ["emu-win-all"]
runs-on: "windows-2022"
steps:
# on Windows Git will auto change line ending to CRLF, not preferable
- name: "Ensure LF line ending"
shell: "cmd"
working-directory: "${{ github.workspace }}"
run: |
git config --local core.autocrlf false
git config --system core.autocrlf false
git config --global core.autocrlf false
# we need branch because it has package scripts
- name: "Checkout branch"
uses: actions/checkout@v4
- name: "Clone third-party deps (deps/win)"
uses: actions/checkout@v4
with:
ref: "third-party/deps/win"
path: "${{env.THIRD_PARTY_BASE_DIR}}/deps/win"
# download artifacts
- name: "Download emu build artifacts (Win)"
uses: actions/download-artifact@v4
with:
path: "build/win"
pattern: "emu-win-*-${{ github.sha }}"
merge-multiple: true
# print files
- name: "Print files"
shell: "cmd"
working-directory: "${{ github.workspace }}"
run: |
dir /s /b /a:-d build\win
# package (release mode)
- name: "Package build (release)"
shell: "cmd"
working-directory: "${{ github.workspace }}"
run: package_win.bat vs2022\release
# package (debug mode)
- name: "Package build (debug)"
shell: "cmd"
working-directory: "${{ github.workspace }}"
run: package_win.bat vs2022\debug 1
# release (debug + release modes) if this is a tag push
- name: "Release"
if: startsWith(github.ref, 'refs/tags/')
uses: softprops/action-gh-release@v2
with:
files: "build/package/win/**/*"
# upload artifacts/packages if this is a manual run
- name: "Upload release package"
if: ${{ !startsWith(github.ref, 'refs/tags/') }}
uses: actions/upload-artifact@v4
with:
name: "release-emu-win-release-${{ github.sha }}"
path: "build/package/win/vs2022/*release*"
if-no-files-found: "error"
compression-level: 0
retention-days: 7
- name: "Upload debug package"
if: ${{ !startsWith(github.ref, 'refs/tags/') }}
uses: actions/upload-artifact@v4
with:
name: "release-emu-win-debug-${{ github.sha }}"
path: "build/package/win/vs2022/*debug*"
if-no-files-found: "error"
compression-level: 0
retention-days: 7
emu-linux-all:
name: "Emu linux all"
if: ${{ !cancelled() }}
uses: "./.github/workflows/emu-build-all-linux.yml"
emu-linux-prep:
needs: ["emu-linux-all"]
runs-on: "ubuntu-20.04"
steps:
# we need branch because it has package scripts
- name: "Checkout branch"
uses: actions/checkout@v4
- name: "Clone third-party deps (deps/linux)"
uses: actions/checkout@v4
with:
ref: "third-party/deps/linux"
path: "${{env.THIRD_PARTY_BASE_DIR}}/deps/linux"
# download artifacts
- name: "Download emu build artifacts (linux)"
uses: actions/download-artifact@v4
with:
path: "build/linux"
pattern: "emu-linux-*-${{ github.sha }}"
merge-multiple: true
# fix folder permissions! not sure why this fails
# nested subdirs "build/linux/release" cause permission problems
- name: "Give all permissions to repo folder"
shell: "bash"
working-directory: "${{ github.workspace }}"
run: sudo chmod -R 777 "${{ github.workspace }}" && sudo chmod 777 package_linux.sh
# print files
- name: "Print files"
shell: "bash"
working-directory: "${{ github.workspace }}"
run: |
ls -la build/linux/*/*
# downlaod ubuntu packages
- name: "Download required Ubuntu packages"
shell: "bash"
working-directory: "${{ github.workspace }}"
run: |
sudo apt update || exit 1
sudo apt install tar -y || exit 1
# package (release mode)
- name: "Package build (release)"
shell: "bash"
working-directory: "${{ github.workspace }}"
run: ./package_linux.sh gmake2/release
# package (debug mode)
- name: "Package build (debug)"
shell: "bash"
working-directory: "${{ github.workspace }}"
run: ./package_linux.sh gmake2/debug 1
# release (debug + release modes) if this is a tag push
- name: "Release"
if: startsWith(github.ref, 'refs/tags/')
uses: softprops/action-gh-release@v2
with:
files: "build/package/linux/**/*"
# upload artifacts/packages if this is a manual run
- name: "Upload release package"
if: ${{ !startsWith(github.ref, 'refs/tags/') }}
uses: actions/upload-artifact@v4
with:
name: "release-emu-linux-release-${{ github.sha }}"
path: "build/package/linux/gmake2/*release*"
if-no-files-found: "error"
compression-level: 0
retention-days: 7
- name: "Upload debug package"
if: ${{ !startsWith(github.ref, 'refs/tags/') }}
uses: actions/upload-artifact@v4
with:
name: "release-emu-linux-debug-${{ github.sha }}"
path: "build/package/linux/gmake2/*debug*"
if-no-files-found: "error"
compression-level: 0
retention-days: 7
gen_emu_script-win:
needs: ["emu-win-all"] # add emu-win-all to wait for emu build to complete, so that we include the latest dlls and tools in generate_emu_config
name: "Gen emu config win"
if: ${{ !cancelled() }}
uses: "./.github/workflows/gen_emu_config-build-win.yml"
gen_emu_script-win-prep:
needs: ["gen_emu_script-win"]
runs-on: "windows-2022"
steps:
# on Windows Git will auto change line ending to CRLF, not preferable
- name: "Ensure LF line ending"
shell: "cmd"
working-directory: "${{ github.workspace }}"
run: |
git config --local core.autocrlf false
git config --system core.autocrlf false
git config --global core.autocrlf false
# we need branch because it has package scripts
- name: "Checkout branch"
uses: actions/checkout@v4
- name: "Clone third-party deps (deps/win)"
uses: actions/checkout@v4
with:
ref: "third-party/deps/win"
path: "${{env.THIRD_PARTY_BASE_DIR}}/deps/win"
# download artifacts
- name: "Download script build artifacts (Win)"
uses: actions/download-artifact@v4
with:
path: "tools/generate_emu_config/bin/win"
pattern: "generate_emu_config-win-*"
merge-multiple: true
# package
- name: "Package script"
shell: "cmd"
working-directory: "tools/generate_emu_config"
run: package_win.bat
# release tag
- name: "Release"
if: startsWith(github.ref, 'refs/tags/')
uses: softprops/action-gh-release@v2
with:
files: "tools/generate_emu_config/bin/package/win/**/*"
# upload artifact/package if this is a manual run
- name: "Upload release package"
if: ${{ !startsWith(github.ref, 'refs/tags/') }}
uses: actions/upload-artifact@v4
with:
name: "release-generate_emu_config-win-${{ github.sha }}"
path: "tools/generate_emu_config/bin/package/win/**/*"
if-no-files-found: "error"
compression-level: 9
retention-days: 7
gen_emu_script-linux:
needs: ["emu-linux-all"] # add emu-linux-all to wait for emu build to complete (not really needed but included for better build matrix visualization)
name: "Gen emu config linux"
if: ${{ !cancelled() }}
uses: "./.github/workflows/gen_emu_config-build-linux.yml"
gen_emu_script-linux-prep:
needs: ["gen_emu_script-linux"]
runs-on: "ubuntu-20.04"
steps:
# we need branch because it has package scripts
- name: "Checkout branch"
uses: actions/checkout@v4
# download artifacts
- name: "Download script build artifacts (linux)"
uses: actions/download-artifact@v4
with:
path: "tools/generate_emu_config/bin/linux"
pattern: "generate_emu_config-linux-*"
merge-multiple: true
# fix folder permissions! not sure why this fails
# nested subdirs "build/linux/release" cause permission problems
- name: "Give all permissions to repo folder"
shell: "bash"
working-directory: "${{ github.workspace }}"
run: sudo chmod -R 777 "${{ github.workspace }}"
# package
- name: "Package script"
shell: "bash"
working-directory: "tools/generate_emu_config"
run: sudo chmod 777 package_linux.sh && sudo ./package_linux.sh
# release tag
- name: "Release"
if: startsWith(github.ref, 'refs/tags/')
uses: softprops/action-gh-release@v2
with:
files: "tools/generate_emu_config/bin/package/linux/**/*"
# upload artifact/package if this is a manual run
- name: "Upload release package"
if: ${{ !startsWith(github.ref, 'refs/tags/') }}
uses: actions/upload-artifact@v4
with:
name: "release-generate_emu_config-linux-${{ github.sha }}"
path: "tools/generate_emu_config/bin/package/linux/**/*"
if-no-files-found: "error"
compression-level: 9
retention-days: 7
migrate_gse_script-win:
needs: ["emu-win-all"] # add emu-win-all to wait for emu build to complete, so that we include the latest dlls and tools in migrate_gse
name: "Migrate GSE win"
if: ${{ !cancelled() }}
uses: "./.github/workflows/migrate_gse-build-win.yml"
migrate_gse_script-win-prep:
needs: ["migrate_gse_script-win"]
runs-on: "windows-2022"
steps:
# on Windows Git will auto change line ending to CRLF, not preferable
- name: "Ensure LF line ending"
shell: "cmd"
working-directory: "${{ github.workspace }}"
run: |
git config --local core.autocrlf false
git config --system core.autocrlf false
git config --global core.autocrlf false
# we need branch because it has package scripts
- name: "Checkout branch"
uses: actions/checkout@v4
- name: "Clone third-party deps (deps/win)"
uses: actions/checkout@v4
with:
ref: "third-party/deps/win"
path: "${{env.THIRD_PARTY_BASE_DIR}}/deps/win"
# download artifacts
- name: "Download script build artifacts (Win)"
uses: actions/download-artifact@v4
with:
path: "tools/migrate_gse/bin/win"
pattern: "migrate_gse-win-*"
merge-multiple: true
# package
- name: "Package script"
shell: "cmd"
working-directory: "tools/migrate_gse"
run: package_win.bat
# release tag
- name: "Release"
if: startsWith(github.ref, 'refs/tags/')
uses: softprops/action-gh-release@v2
with:
files: "tools/migrate_gse/bin/package/win/**/*"
# upload artifact/package if this is a manual run
- name: "Upload release package"
if: ${{ !startsWith(github.ref, 'refs/tags/') }}
uses: actions/upload-artifact@v4
with:
name: "release-migrate_gse-win-${{ github.sha }}"
path: "tools/migrate_gse/bin/package/win/**/*"
if-no-files-found: "error"
compression-level: 9
retention-days: 7
migrate_gse_script-linux:
needs: ["emu-linux-all"] # add emu-linux-all to wait for emu build to complete (not really needed but included for better build matrix visualization)
name: Migrate GSE linux
if: ${{ !cancelled() }}
uses: "./.github/workflows/migrate_gse-build-linux.yml"
migrate_gse_script-linux-prep:
needs: ["migrate_gse_script-linux"]
runs-on: "ubuntu-20.04"
steps:
# we need branch because it has package scripts
- name: "Checkout branch"
uses: actions/checkout@v4
# download artifacts
- name: "Download script build artifacts (linux)"
uses: actions/download-artifact@v4
with:
path: "tools/migrate_gse/bin/linux"
pattern: "migrate_gse-linux-*"
merge-multiple: true
# fix folder permissions! not sure why this fails
# nested subdirs "build/linux/release" cause permission problems
- name: "Give all permissions to repo folder"
shell: "bash"
working-directory: "${{ github.workspace }}"
run: sudo chmod -R 777 "${{ github.workspace }}"
# package
- name: "Package script"
shell: "bash"
working-directory: "tools/migrate_gse"
run: sudo chmod 777 package_linux.sh && sudo ./package_linux.sh
# release tag
- name: "Release"
if: startsWith(github.ref, 'refs/tags/')
uses: softprops/action-gh-release@v2
with:
files: "tools/migrate_gse/bin/package/linux/**/*"
# upload artifact/package if this is a manual run
- name: "Upload release package"
if: ${{ !startsWith(github.ref, 'refs/tags/') }}
uses: actions/upload-artifact@v4
with:
name: "release-migrate_gse-linux-${{ github.sha }}"
path: "tools/migrate_gse/bin/package/linux/**/*"
if-no-files-found: "error"
compression-level: 9
retention-days: 7

67
.gitignore vendored
View File

@ -1,67 +0,0 @@
# IDE
**/.vs
**/.vscode
# PYTHON
**/.venv
**/__pycache__
# PROTOBUF
/proto_gen
# SPECIFIC
/build
/third-party
# TOOLS
# generate_emu_config
/tools/generate_emu_config/.py*/
/tools/generate_emu_config/.env*/
/tools/generate_emu_config/bin
/tools/generate_emu_config/_DEFAULT/0/steam_api.dll
/tools/generate_emu_config/_DEFAULT/0/steam_api.7z
/tools/generate_emu_config/_DEFAULT/0/steam_api64.dll
/tools/generate_emu_config/_DEFAULT/0/steam_api64.7z
/tools/generate_emu_config/_DEFAULT/0/steam_api.7z
/tools/generate_emu_config/_DEFAULT/0/steam_api64.dll
/tools/generate_emu_config/_DEFAULT/0/steam_api64.7z
/tools/generate_emu_config/_DEFAULT/0/steam_misc/tools/generate_interfaces/generate_interfaces.7z
/tools/generate_emu_config/_DEFAULT/0/steam_misc/tools/generate_interfaces/generate_interfaces.exe
/tools/generate_emu_config/_DEFAULT/0/steam_misc/tools/generate_interfaces/generate_interfaces64.exe
/tools/generate_emu_config/_DEFAULT/0/steam_misc/tools/lobby_connect/lobby_connect.7z
/tools/generate_emu_config/_DEFAULT/0/steam_misc/tools/lobby_connect/lobby_connect.exe
/tools/generate_emu_config/_DEFAULT/0/steam_misc/tools/lobby_connect/lobby_connect64.exe
/tools/generate_emu_config/_OUTPUT/
/tools/generate_emu_config/login_temp/
/tools/generate_emu_config/**/my_login.txt
# migrate_gse
/tools/migrate_gse/.py*/
/tools/migrate_gse/.env*/
/tools/migrate_gse/bin
/tools/migrate_gse/_DEFAULT/0/steam_api.dll
/tools/migrate_gse/_DEFAULT/0/steam_api.7z
/tools/migrate_gse/_DEFAULT/0/steam_api64.dll
/tools/migrate_gse/_DEFAULT/0/steam_api64.7z
/tools/migrate_gse/_DEFAULT/0/steam_api.7z
/tools/migrate_gse/_DEFAULT/0/steam_api64.dll
/tools/migrate_gse/_DEFAULT/0/steam_api64.7z
/tools/migrate_gse/_DEFAULT/0/steam_misc/tools/generate_interfaces/generate_interfaces.7z
/tools/migrate_gse/_DEFAULT/0/steam_misc/tools/generate_interfaces/generate_interfaces.exe
/tools/migrate_gse/_DEFAULT/0/steam_misc/tools/generate_interfaces/generate_interfaces64.exe
/tools/migrate_gse/_DEFAULT/0/steam_misc/tools/lobby_connect/lobby_connect.7z
/tools/migrate_gse/_DEFAULT/0/steam_misc/tools/lobby_connect/lobby_connect.exe
/tools/migrate_gse/_DEFAULT/0/steam_misc/tools/lobby_connect/lobby_connect64.exe
/tools/migrate_gse/_OUTPUT/

34
.gitmodules vendored
View File

@ -1,34 +0,0 @@
[submodule "third-party/build/win"]
path = third-party/build/win
url = ./
branch = third-party/build/win
[submodule "third-party/build/linux"]
path = third-party/build/linux
url = ./
branch = third-party/build/linux
[submodule "third-party/common/win"]
path = third-party/common/win
url = ./
branch = third-party/common/win
[submodule "third-party/common/linux"]
path = third-party/common/linux
url = ./
branch = third-party/common/linux
[submodule "third-party/deps/win"]
path = third-party/deps/win
url = ./
branch = third-party/deps/win
[submodule "third-party/deps/linux"]
path = third-party/deps/linux
url = ./
branch = third-party/deps/linux
[submodule "third-party/deps/common"]
path = third-party/deps/common
url = ./
branch = third-party/deps/common

BIN
7za/7za Normal file
View File

Binary file not shown.

98
7za/SOURCE.txt Normal file
View File

@ -0,0 +1,98 @@
#### INFO
https://sourceforge.net/projects/p7zip/
VERSION: https://sourceforge.net/projects/p7zip/files/p7zip/16.02/
#### LICENSE
7-Zip
~~~~~
License for use and distribution
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
7-Zip Copyright (C) 1999-2023 Igor Pavlov.
The licenses for files are:
1) 7z.dll:
- The "GNU LGPL" as main license for most of the code
- The "GNU LGPL" with "unRAR license restriction" for some code
- The "BSD 3-clause License" for some code
2) All other files: the "GNU LGPL".
Redistributions in binary form must reproduce related license information from this file.
Note:
You can use 7-Zip on any computer, including a computer in a commercial
organization. You don't need to register or pay for 7-Zip.
GNU LGPL information
--------------------
This library is free software; you can redistribute it and/or
modify it under the terms of the GNU Lesser General Public
License as published by the Free Software Foundation; either
version 2.1 of the License, or (at your option) any later version.
This library is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
Lesser General Public License for more details.
You can receive a copy of the GNU Lesser General Public License from
http://www.gnu.org/
BSD 3-clause License
--------------------
The "BSD 3-clause License" is used for the code in 7z.dll that implements LZFSE data decompression.
That code was derived from the code in the "LZFSE compression library" developed by Apple Inc,
that also uses the "BSD 3-clause License":
----
Copyright (c) 2015-2016, Apple Inc. All rights reserved.
Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:
1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer
in the documentation and/or other materials provided with the distribution.
3. Neither the name of the copyright holder(s) nor the names of any contributors may be used to endorse or promote products derived
from this software without specific prior written permission.
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE
COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
----
unRAR license restriction
-------------------------
The decompression engine for RAR archives was developed using source
code of unRAR program.
All copyrights to original unRAR code are owned by Alexander Roshal.
The license for original unRAR code has the following restriction:
The unRAR sources cannot be used to re-create the RAR compression algorithm,
which is proprietary. Distribution of modified unRAR sources in separate form
or as a part of other software is permitted, provided that it is clearly
stated in the documentation and source comments that the code may
not be used to develop a RAR (WinRAR) compatible archiver.
--
Igor Pavlov

1036
CHANGELOG.md
View File

File diff suppressed because it is too large Load Diff

2556
CREDITS.md
View File

File diff suppressed because it is too large Load Diff

165
LICENSE
View File

@ -1,165 +0,0 @@
GNU LESSER GENERAL PUBLIC LICENSE
Version 3, 29 June 2007
Copyright (C) 2007 Free Software Foundation, Inc. <https://fsf.org/>
Everyone is permitted to copy and distribute verbatim copies
of this license document, but changing it is not allowed.
This version of the GNU Lesser General Public License incorporates
the terms and conditions of version 3 of the GNU General Public
License, supplemented by the additional permissions listed below.
0. Additional Definitions.
As used herein, "this License" refers to version 3 of the GNU Lesser
General Public License, and the "GNU GPL" refers to version 3 of the GNU
General Public License.
"The Library" refers to a covered work governed by this License,
other than an Application or a Combined Work as defined below.
An "Application" is any work that makes use of an interface provided
by the Library, but which is not otherwise based on the Library.
Defining a subclass of a class defined by the Library is deemed a mode
of using an interface provided by the Library.
A "Combined Work" is a work produced by combining or linking an
Application with the Library. The particular version of the Library
with which the Combined Work was made is also called the "Linked
Version".
The "Minimal Corresponding Source" for a Combined Work means the
Corresponding Source for the Combined Work, excluding any source code
for portions of the Combined Work that, considered in isolation, are
based on the Application, and not on the Linked Version.
The "Corresponding Application Code" for a Combined Work means the
object code and/or source code for the Application, including any data
and utility programs needed for reproducing the Combined Work from the
Application, but excluding the System Libraries of the Combined Work.
1. Exception to Section 3 of the GNU GPL.
You may convey a covered work under sections 3 and 4 of this License
without being bound by section 3 of the GNU GPL.
2. Conveying Modified Versions.
If you modify a copy of the Library, and, in your modifications, a
facility refers to a function or data to be supplied by an Application
that uses the facility (other than as an argument passed when the
facility is invoked), then you may convey a copy of the modified
version:
a) under this License, provided that you make a good faith effort to
ensure that, in the event an Application does not supply the
function or data, the facility still operates, and performs
whatever part of its purpose remains meaningful, or
b) under the GNU GPL, with none of the additional permissions of
this License applicable to that copy.
3. Object Code Incorporating Material from Library Header Files.
The object code form of an Application may incorporate material from
a header file that is part of the Library. You may convey such object
code under terms of your choice, provided that, if the incorporated
material is not limited to numerical parameters, data structure
layouts and accessors, or small macros, inline functions and templates
(ten or fewer lines in length), you do both of the following:
a) Give prominent notice with each copy of the object code that the
Library is used in it and that the Library and its use are
covered by this License.
b) Accompany the object code with a copy of the GNU GPL and this license
document.
4. Combined Works.
You may convey a Combined Work under terms of your choice that,
taken together, effectively do not restrict modification of the
portions of the Library contained in the Combined Work and reverse
engineering for debugging such modifications, if you also do each of
the following:
a) Give prominent notice with each copy of the Combined Work that
the Library is used in it and that the Library and its use are
covered by this License.
b) Accompany the Combined Work with a copy of the GNU GPL and this license
document.
c) For a Combined Work that displays copyright notices during
execution, include the copyright notice for the Library among
these notices, as well as a reference directing the user to the
copies of the GNU GPL and this license document.
d) Do one of the following:
0) Convey the Minimal Corresponding Source under the terms of this
License, and the Corresponding Application Code in a form
suitable for, and under terms that permit, the user to
recombine or relink the Application with a modified version of
the Linked Version to produce a modified Combined Work, in the
manner specified by section 6 of the GNU GPL for conveying
Corresponding Source.
1) Use a suitable shared library mechanism for linking with the
Library. A suitable mechanism is one that (a) uses at run time
a copy of the Library already present on the user's computer
system, and (b) will operate properly with a modified version
of the Library that is interface-compatible with the Linked
Version.
e) Provide Installation Information, but only if you would otherwise
be required to provide such information under section 6 of the
GNU GPL, and only to the extent that such information is
necessary to install and execute a modified version of the
Combined Work produced by recombining or relinking the
Application with a modified version of the Linked Version. (If
you use option 4d0, the Installation Information must accompany
the Minimal Corresponding Source and Corresponding Application
Code. If you use option 4d1, you must provide the Installation
Information in the manner specified by section 6 of the GNU GPL
for conveying Corresponding Source.)
5. Combined Libraries.
You may place library facilities that are a work based on the
Library side by side in a single library together with other library
facilities that are not Applications and are not covered by this
License, and convey such a combined library under terms of your
choice, if you do both of the following:
a) Accompany the combined library with a copy of the same work based
on the Library, uncombined with any other library facilities,
conveyed under the terms of this License.
b) Give prominent notice with the combined library that part of it
is a work based on the Library, and explaining where to find the
accompanying uncombined form of the same work.
6. Revised Versions of the GNU Lesser General Public License.
The Free Software Foundation may publish revised and/or new versions
of the GNU Lesser General Public License from time to time. Such new
versions will be similar in spirit to the present version, but may
differ in detail to address new problems or concerns.
Each version is given a distinguishing version number. If the
Library as you received it specifies that a certain numbered version
of the GNU Lesser General Public License "or any later version"
applies to it, you have the option of following the terms and
conditions either of that published version or of any later version
published by the Free Software Foundation. If the Library as you
received it does not specify a version number of the GNU Lesser
General Public License, you may choose any version of the GNU Lesser
General Public License ever published by the Free Software Foundation.
If the Library as you received it specifies that a proxy can decide
whether future versions of the GNU Lesser General Public License shall
apply, that proxy's public statement of acceptance of any version is
permanent authorization for you to choose that version for the
Library.

365
README.md
View File

@ -1,365 +0,0 @@
## :large_orange_diamond: **Goldberg Steam Emu**
Fork of https://gitlab.com/Mr_Goldberg/goldberg_emulator with a lot of fixes, improvements, additional features and a completely reworked file structure.
Fork originally made by wizark952. This is latest version of it.
### Feel free to make a PR.
---
:red_circle:
**This fork is not a takeover, not a resurrection of the original project, and not a replacement.**
**You are highly encouraged to fork/clone it and do whatever you want with it.**
:red_circle:
---
## **Compatibility**
This fork is incompatible with the original repo, lots of things has changed and might be even broken.
If something doesn't work, feel free to create a pull request with the appropriate fix, otherwise ignore this fork and use the original emu.
---
## **Credits**
Thanks to everyone contributing to this project in any way possible, we try to keep the [CHANGELOG.md](./CHANGELOG.md) updated with all the changes and their authors.
This project depends on many third-party libraries and tools, credits to them for their amazing work, you can find their listing here in [CREDITS.md](./CREDITS.md).
---
# How to use the emu
* **Always generate the interfaces file using the `find_interfaces` tool.**
* **Generate the proper app configuration using the `generate_emu_config` tool.**
* **If things don't work, try the `ColdClientLoader` setup.**
You can find some guides, helper tools and scripts here:
**These guides, tools and scripts are maintained by their authors.
Before using them, it's always a good idea to first make sure they are updated and designed to support all features of this fork of the emulator.**
* **[How to use Goldberg Emulator](https://rentry.co/goldberg_emulator)**
* **[Steam Emu Utility](https://github.com/turusudiro/SteamEmuUtility)**
* **[GSE-Generator](https://github.com/brunolee-GIT/GSE-Generator)**
You can also find instructions here in [README.release.md](./post_build/README.release.md)
---
# **Compiling**
## One time setup
### **Cloning the repo**
Disable automatic CRLF handling:
*Locally*
```shell
git config --local core.autocrlf false
```
*Or globally/system wide*
```shell
git config --system core.autocrlf false
git config --global core.autocrlf false
```
Clone the repo and its submodules **recursively**
```shell
git clone --recurse-submodules -j8 https://github.com/otavepto/gbe_fork.git
```
The switch `-j8` is optional, it allows Git to fetch up to 8 submodules
It is adviseable to always checkout submodules every now and then, to make sure they're up to date
```shell
git submodule update --init --recursive --remote
```
### For Windows:
* You need Windows 10 or 8.1 + WDK
* Using Visual Studio, install `Visual Studio 2022 Community`: https://visualstudio.microsoft.com/vs/community/
* Select the Workload `Desktop development with C++`
* In the `Individual componenets` scroll to the buttom and select the **latest** version of `Windows XX SDK (XX.X...)`
For example `Windows 11 SDK (10.0.22621.0)`
* Using `MSYS2` **this is currently experimental and will not work due to ABI differences**: https://www.msys2.org/
<details>
<summary>steps</summary>
* To build 64-bit binaries use either the [environment](https://www.msys2.org/docs/environments/) `UCRT64` or `MINGW64` then install the GCC toolchain
`UCRT64`
```shell
pacman -S mingw-w64-ucrt-x86_64-gcc
```
`MINGW64`
```shell
pacman -S mingw-w64-i686-gcc
```
* To build 32-bit binaries use the environment `MINGW32` then install the GCC toolchain
```shell
pacman -S mingw-w64-i686-gcc
```
</details>
* Python 3.10 or above: https://www.python.org/downloads/windows/
After installation, make sure it works
```batch
python --version
```
* *(Optional)* Install a GUI for Git like [GitHub Desktop](https://desktop.github.com/), or [Sourcetree](https://www.sourcetreeapp.com/)
### For Linux:
* Ubuntu 20.04 LTS: https://ubuntu.com/download/desktop
* Ubuntu required packages:
```shell
sudo apt update -y
sudo apt install -y coreutils # echo, printf, etc...
sudo apt install -y build-essential
sudo apt install -y gcc-multilib # needed for 32-bit builds
sudo apt install -y g++-multilib
sudo apt install -y libglx-dev # needed for overlay build (header files such as GL/glx.h)
sudo apt install -y libgl-dev # needed for overlay build (header files such as GL/gl.h)
```
*(Optional)* Additional packages
```shell
sudo apt install -y clang # clang compiler
sudo apt install -y binutils # contains the tool 'readelf' mainly, and other usefull binary stuff
```
* Python 3.10 or above
```shell
sudo apt update -y
sudo apt install -y software-properties-common
sudo add-apt-repository ppa:deadsnakes/ppa -y
sudo apt update -y
sudo apt install -y "python3.12"
sudo apt install -y "python3.12-dev"
sudo apt install -y "python3.12-venv"
sudo apt install -y python3-dev
# make sure it works
python3.12 --version
```
### **Building dependencies**
These are third party libraries needed to build the emu later, they are linked with the emu during its build process.
You don't need to build these dependencies every time, they rarely get updated.
The only times you'll need to rebuild them is either when their separete build folder was accedentally deleted, or when the dependencies were updated.
<br/>
#### On Windows:
Open CMD in the repo folder, then run the following
* To build using `Visual Studio`
```batch
set "CMAKE_GENERATOR=Visual Studio 17 2022"
third-party\common\win\premake\premake5.exe --file=premake5-deps.lua --64-build --32-build --all-ext --all-build --verbose --os=windows vs2022
```
* To build using `MSYS2` **this is currently experimental and will not work due to ABI differences**
<details>
<summary>steps</summary>
*(Optional)* In both cases below, you can use `Clang` compiler instead of `GCC` by running these 2 commands in the same terminal instance
```shell
export CC="clang"
export CXX="clang++"
```
* To build 64-bit binaries (`UCRT64` or `MINGW64`)
```shell
export CMAKE_GENERATOR="MSYS Makefiles"
./third-party/common/win/premake/premake5.exe --file=premake5-deps.lua --64-build --all-ext --all-build --verbose --os=windows gmake2
```
* To build 32-bit binaries (`MINGW32`)
```shell
export CMAKE_GENERATOR="MSYS Makefiles"
./third-party/common/win/premake/premake5.exe --file=premake5-deps.lua --32-build --all-ext --all-build --verbose --os=windows gmake2
```
</details>
This will:
* Extract all third party dependencies from the folder `third-party` into the folder `build\deps\win`
* Build all dependencies
#### On Linux:
Open a terminal in the repo folder
*(Optional)* You can use `Clang` compiler instead of `GCC` by running these 2 commands in the current terminal instance
```shell
export CC="clang"
export CXX="clang++"
```
Then run the following
```shell
export CMAKE_GENERATOR="Unix Makefiles"
./third-party/common/linux/premake/premake5 --file=premake5-deps.lua --64-build --32-build --all-ext --all-build --verbose --os=linux gmake2
```
This will:
* Extract all third party dependencies from the folder `third-party` into the folder `build/deps/linux`
* Build all dependencies (32-bit and 64-bit)
---
## **Building the emu**
### On Windows:
Open CMD in the repo folder, then run the following
* For `Visual Studio 2022`
```batch
third-party\common\win\premake\premake5.exe --file=premake5.lua --genproto --os=windows vs2022
```
You can then go to the folder `build\project\vs2022\win` and open the produced `.sln` file in Visual Studio.
Or, if you prefer to do it from command line, open the `Developer Command Prompt for VS 2022` inside the above folder, then:
```batch
msbuild /nologo /v:n /p:Configuration=release,Platform=Win32 gbe.sln
msbuild /nologo /v:n /p:Configuration=release,Platform=x64 gbe.sln
```
* For `MSYS2` **this is currently experimental and will not work due to ABI differences**
<details>
<summary>steps</summary>
```shell
./third-party/common/win/premake/premake5.exe --file=premake5.lua --genproto --os=windows gmake2
cd ./build/project/gmake2/win
```
*(Optional)* You can use `Clang` compiler instead of `GCC` by running these 2 commands in the current terminal instance
```shell
export CC="clang"
export CXX="clang++"
```
* 64-bit build (`UCRT64` or `MINGW64`)
```shell
make config=release_x64 -j 8 all
```
* 32-bit build (`MINGW32`)
```shell
make config=release_x32 -j 8 all
```
To see all possible build targets
```shell
make help
```
</details>
This will build a release version of the emu in the folder `build\win\<toolchain>\release`
An example script `build_win_premake.bat` is available, check it out
<br/>
### On Linux:
Open a terminal in the repo folder, then run the following
```shell
./third-party/common/linux/premake/premake5 --file=premake5.lua --genproto --os=linux gmake2
cd ./build/project/gmake2/linux
```
*(Optional)* You can use `Clang` compiler instead of `GCC` by running these 2 commands in the current terminal instance
```shell
export CC="clang"
export CXX="clang++"
```
Then run the following
```shell
make config=release_x32 -j 8 all
make config=release_x64 -j 8 all
```
To see all possible build targets
```shell
make help
```
This will build a release version of the emu in the folder `build/linux/<toolchain>/release`
An example script `build_linux_premake.sh` is available, check it out
---
## **Building the tool `generate_emu_config`**
Navigate to the folder `tools/generate_emu_config/` then
### On Windows:
Open CMD then:
1. Create python virtual environemnt and install the required packages/dependencies
```batch
recreate_venv_win.bat
```
2. Build the tool using `pyinstaller`
```batch
rebuild_win.bat
```
This will build the tool inside `bin\win`
### On Linux:
Open bash terminal then:
1. Create python virtual environemnt and install the required packages/dependencies
```shell
sudo ./recreate_venv_linux.sh
```
You might need to edit this script to use a different python version.
Find this line and change it:
```shell
python_package="python3.12"
```
2. Build the tool using `pyinstaller`
```shell
./rebuild_linux.sh
```
This will build the tool inside `bin/linux`
---
## **Using Github CI as a builder**
This is really slow and mainly intended for the CI Workflow scripts, but you can use it as another outlet if you can't build locally.
**You have to fork the repo first**.
### Initial setup
In your fork, open the `Settings` tab from the top, then:
* From the left side panel select `Actions` -> `General`
* In the section `Actions permissions` select `Allow all actions and reusable workflows`
* Scroll down, and in the section `Workflow permissions` select `Read and write permissions`
* *(Optional)* In the section `Artifact and log retention`, you can specify the amount of days to keep the build artifacts/archives.
It is recommended to set a reasonable number like 3-4 days, otherwise you may consume your packages storage if you use Github as a builder frequently, more details here: https://docs.github.com/en/get-started/learning-about-github/githubs-plans
### Manual trigger
1. Go to the `Actions` tab in your fork
2. Select the emu dependencies Workflow (ex: `Emu third-party dependencies (Windows) `) and run it on the **main** branch (ex: `dev`).
Dependencies not created on the main branch won't be recognized by other branches or subsequent runs
3. Select one of the Workflow scripts from the left side panel, for example `Build all emu variants (Windows)`
3. On the top-right, select `Run workflow` -> select the desired branch (for example `dev`) -> press the button `Run workflow`
4. When it's done, many packages (called build artifacts) will be created for that workflow.
Make sure to select the workflow again to view its history, then select the last run at the very top to view its artifacts
<br/>
Important note:
---
When you build the dependencies workflows, they will be cached to decrease the build times of the next triggers and avoid unnecessary/wasteful build process.
This will cause a problem if at any time the third-party dependencies were updated, in that case you need to manually delete the cache, in your fork:
1. Go to the `Actions` tab at the top
2. Select `Caches` from the left side panel
3. Delete the corresponding cache
<br/>
---
## ***(Optional)* Packaging**
This step is intended for Github CI/Workflow, but you can create a package locally.
### On Windows:
Open CMD in the repos's directory, then run this script
```batch
package_win.bat <build_folder>
```
`build_folder` is any folder inside `build\win`, for example: `vs2022\release`
The above example will create a `.7z` archive inside `build\package\win\`
### On Linux:
Open bash terminal in the repos's directory, then run this script
```shell
package_linux.sh <build_folder>
```
`build_folder` is any folder inside `build/linux`, for example: `gmake2/release`
The above example will create a compressed `.tar` archive inside `build/package/linux/`

71
build_linux_premake.sh
View File

@ -1,71 +0,0 @@
#!/usr/bin/env bash
function help_page () {
echo "./$(basename "$0") [switches]"
echo "switches:"
echo " --deps: rebuild third-party dependencies"
echo " --help: show this page"
}
# use 70%
build_threads="$(( $(getconf _NPROCESSORS_ONLN 2>/dev/null || echo 0) * 70 / 100 ))"
[[ $build_threads -lt 2 ]] && build_threads=2
BUILD_DEPS=0
for (( i=1; i<=$#; ++i )); do
arg="${!i}"
if [[ "$arg" = "--deps" ]]; then
BUILD_DEPS=1
elif [[ "$arg" = "--help" ]]; then
help_page
exit 0
else
echo "invalid arg $arg" 1>&2
exit 1
fi
done
premake_exe=./"third-party/common/linux/premake/premake5"
if [[ ! -f "$premake_exe" ]]; then
echo "preamke wasn't found" 1>&2
exit 1
fi
chmod 777 "$premake_exe"
# build deps
if [[ $BUILD_DEPS = 1 ]]; then
export CMAKE_GENERATOR="Unix Makefiles"
"$premake_exe" --file="premake5-deps.lua" --all-ext --all-build --64-build --32-build --verbose --clean --j=$build_threads --os=linux gmake2 || {
exit 1;
}
fi
"$premake_exe" --genproto --os=linux gmake2 || {
exit 1;
}
pushd ./"build/project/gmake2/linux"
# you can select individual or all
echo; echo building debug x64
make -j $build_threads config=debug_x64 || {
exit 1;
}
echo; echo building debug x32
make -j $build_threads config=debug_x32 || {
exit 1;
}
echo; echo building release x64
make -j $build_threads config=release_x64 || {
exit 1;
}
echo; echo building release x32
make -j $build_threads config=release_x32 || {
exit 1;
}
popd

112
build_win_premake.bat
View File

@ -1,112 +0,0 @@
@echo off
setlocal EnableDelayedExpansion
cd /d "%~dp0"
set /a "MAX_THREADS=2"
if defined NUMBER_OF_PROCESSORS (
:: use 70%
set /a "MAX_THREADS=%NUMBER_OF_PROCESSORS% * 70 / 100"
if %MAX_THREADS% lss 1 (
set /a "MAX_THREADS=1"
)
)
set /a "BUILD_DEPS=0"
:args_loop
if "%~1" equ "" (
goto :args_loop_end
) else if "%~1" equ "--deps" (
set /a "BUILD_DEPS=1"
) else if "%~1" equ "--help" (
goto :help_page
) else (
1>&2 echo:invalid arg %~1
goto :end_script_with_err
)
shift /1
goto :args_loop
:args_loop_end
:: check premake
set "PREMAKE_EXE=third-party\common\win\premake\premake5.exe"
if not exist "%PREMAKE_EXE%" (
1>&2 echo:premake wasn't found
goto :end_script_with_err
)
:: build deps
if %BUILD_DEPS% equ 1 (
set "CMAKE_GENERATOR=Visual Studio 17 2022"
call "%PREMAKE_EXE%" --file="premake5-deps.lua" --64-build --32-build --all-ext --all-build --j=2 --verbose --clean --os=windows vs2022 || (
goto :end_script_with_err
)
goto :end_script
)
:: check vswhere
set "VSWHERE_EXE=third-party\common\win\vswhere\vswhere.exe"
if not exist "%VSWHERE_EXE%" (
1>&2 echo:vswhere wasn't found
goto :end_script_with_err
)
:: check msbuild
set "MSBUILD_EXE="
for /f "tokens=* delims=" %%A in ('"%VSWHERE_EXE%" -prerelease -latest -nocolor -nologo -property installationPath 2^>nul') do (
set "MSBUILD_EXE=%%~A\MSBuild\Current\Bin\MSBuild.exe"
)
if not exist "%MSBUILD_EXE%" (
1>&2 echo:MSBuild wasn't found
goto :end_script_with_err
)
:: create .sln
call "%PREMAKE_EXE%" --file="premake5.lua" --genproto --dosstub --winrsrc --winsign --os=windows vs2022 || (
goto :end_script_with_err
)
:: check .sln
set "SLN_FILE=build\project\vs2022\win\gbe.sln"
if not exist "%SLN_FILE%" (
1>&2 echo:.sln file wasn't found
goto :end_script_with_err
)
:: build .sln
set "BUILD_TYPES=release debug"
set "BUILD_PLATFORMS=x64 Win32"
set "BUILD_TARGETS=api_regular api_experimental steamclient_experimental_stub steamclient_experimental steamclient_experimental_loader steamclient_experimental_extra lib_game_overlay_renderer tool_lobby_connect tool_generate_interfaces"
for %%A in (%BUILD_TYPES%) do (
set "BUILD_TYPE=%%A"
for %%B in (%BUILD_PLATFORMS%) do (
set "BUILD_PLATFORM=%%B"
for %%C in (%BUILD_TARGETS%) do (
set "BUILD_TARGET=%%C"
echo. & echo:building !BUILD_TARGET! !BUILD_TYPE! !BUILD_PLATFORM!
call "%MSBUILD_EXE%" /nologo -m:%MAX_THREADS% -v:n /p:Configuration=!BUILD_TYPE!,Platform=!BUILD_PLATFORM! /target:!BUILD_TARGET! "%SLN_FILE%" || (
goto :end_script_with_err
)
)
)
)
goto :end_script
:end_script
endlocal
exit /b 0
:end_script_with_err
endlocal
exit /b 1
:: show help page
:help_page
echo:"%~nx0" [switches]
echo:switches:
echo: --deps: rebuild third-party dependencies
echo: --help: show this page
goto :end_script

3
build_win_premake_deps.bat
View File

@ -1,3 +0,0 @@
@echo off
call "build_win_premake.bat" --deps

3
build_win_premake_gemu.bat
View File

@ -1,3 +0,0 @@
@echo off
call "build_win_premake.bat"

173
cmake/SOURCE.txt Normal file
View File

@ -0,0 +1,173 @@
#### INFO
https://gitlab.kitware.com/cmake/cmake
VERSION: https://github.com/Kitware/CMake/releases/tag/v3.30.2
#### LICENSE
GNU LESSER GENERAL PUBLIC LICENSE
Version 3, 29 June 2007
Copyright (C) 2007 Free Software Foundation, Inc. <http://fsf.org/>
Everyone is permitted to copy and distribute verbatim copies
of this license document, but changing it is not allowed.
This version of the GNU Lesser General Public License incorporates
the terms and conditions of version 3 of the GNU General Public
License, supplemented by the additional permissions listed below.
0. Additional Definitions.
As used herein, "this License" refers to version 3 of the GNU Lesser
General Public License, and the "GNU GPL" refers to version 3 of the GNU
General Public License.
"The Library" refers to a covered work governed by this License,
other than an Application or a Combined Work as defined below.
An "Application" is any work that makes use of an interface provided
by the Library, but which is not otherwise based on the Library.
Defining a subclass of a class defined by the Library is deemed a mode
of using an interface provided by the Library.
A "Combined Work" is a work produced by combining or linking an
Application with the Library. The particular version of the Library
with which the Combined Work was made is also called the "Linked
Version".
The "Minimal Corresponding Source" for a Combined Work means the
Corresponding Source for the Combined Work, excluding any source code
for portions of the Combined Work that, considered in isolation, are
based on the Application, and not on the Linked Version.
The "Corresponding Application Code" for a Combined Work means the
object code and/or source code for the Application, including any data
and utility programs needed for reproducing the Combined Work from the
Application, but excluding the System Libraries of the Combined Work.
1. Exception to Section 3 of the GNU GPL.
You may convey a covered work under sections 3 and 4 of this License
without being bound by section 3 of the GNU GPL.
2. Conveying Modified Versions.
If you modify a copy of the Library, and, in your modifications, a
facility refers to a function or data to be supplied by an Application
that uses the facility (other than as an argument passed when the
facility is invoked), then you may convey a copy of the modified
version:
a) under this License, provided that you make a good faith effort to
ensure that, in the event an Application does not supply the
function or data, the facility still operates, and performs
whatever part of its purpose remains meaningful, or
b) under the GNU GPL, with none of the additional permissions of
this License applicable to that copy.
3. Object Code Incorporating Material from Library Header Files.
The object code form of an Application may incorporate material from
a header file that is part of the Library. You may convey such object
code under terms of your choice, provided that, if the incorporated
material is not limited to numerical parameters, data structure
layouts and accessors, or small macros, inline functions and templates
(ten or fewer lines in length), you do both of the following:
a) Give prominent notice with each copy of the object code that the
Library is used in it and that the Library and its use are
covered by this License.
b) Accompany the object code with a copy of the GNU GPL and this license
document.
4. Combined Works.
You may convey a Combined Work under terms of your choice that,
taken together, effectively do not restrict modification of the
portions of the Library contained in the Combined Work and reverse
engineering for debugging such modifications, if you also do each of
the following:
a) Give prominent notice with each copy of the Combined Work that
the Library is used in it and that the Library and its use are
covered by this License.
b) Accompany the Combined Work with a copy of the GNU GPL and this license
document.
c) For a Combined Work that displays copyright notices during
execution, include the copyright notice for the Library among
these notices, as well as a reference directing the user to the
copies of the GNU GPL and this license document.
d) Do one of the following:
0) Convey the Minimal Corresponding Source under the terms of this
License, and the Corresponding Application Code in a form
suitable for, and under terms that permit, the user to
recombine or relink the Application with a modified version of
the Linked Version to produce a modified Combined Work, in the
manner specified by section 6 of the GNU GPL for conveying
Corresponding Source.
1) Use a suitable shared library mechanism for linking with the
Library. A suitable mechanism is one that (a) uses at run time
a copy of the Library already present on the user's computer
system, and (b) will operate properly with a modified version
of the Library that is interface-compatible with the Linked
Version.
e) Provide Installation Information, but only if you would otherwise
be required to provide such information under section 6 of the
GNU GPL, and only to the extent that such information is
necessary to install and execute a modified version of the
Combined Work produced by recombining or relinking the
Application with a modified version of the Linked Version. (If
you use option 4d0, the Installation Information must accompany
the Minimal Corresponding Source and Corresponding Application
Code. If you use option 4d1, you must provide the Installation
Information in the manner specified by section 6 of the GNU GPL
for conveying Corresponding Source.)
5. Combined Libraries.
You may place library facilities that are a work based on the
Library side by side in a single library together with other library
facilities that are not Applications and are not covered by this
License, and convey such a combined library under terms of your
choice, if you do both of the following:
a) Accompany the combined library with a copy of the same work based
on the Library, uncombined with any other library facilities,
conveyed under the terms of this License.
b) Give prominent notice with the combined library that part of it
is a work based on the Library, and explaining where to find the
accompanying uncombined form of the same work.
6. Revised Versions of the GNU Lesser General Public License.
The Free Software Foundation may publish revised and/or new versions
of the GNU Lesser General Public License from time to time. Such new
versions will be similar in spirit to the present version, but may
differ in detail to address new problems or concerns.
Each version is given a distinguishing version number. If the
Library as you received it specifies that a certain numbered version
of the GNU Lesser General Public License "or any later version"
applies to it, you have the option of following the terms and
conditions either of that published version or of any later version
published by the Free Software Foundation. If the Library as you
received it does not specify a version number of the GNU Lesser
General Public License, you may choose any version of the GNU Lesser
General Public License ever published by the Free Software Foundation.
If the Library as you received it specifies that a proxy can decide
whether future versions of the GNU Lesser General Public License shall
apply, that proxy's public statement of acceptance of any version is
permanent authorization for you to choose that version for the
Library.

BIN
cmake/bin/cmake Normal file
View File

Binary file not shown.

44
cmake/share/aclocal/cmake.m4 Normal file
View File

@ -0,0 +1,44 @@
dnl Distributed under the OSI-approved BSD 3-Clause License. See accompanying
dnl file Copyright.txt or https://cmake.org/licensing for details.
AC_DEFUN([CMAKE_FIND_BINARY],
[AC_ARG_VAR([CMAKE_BINARY], [path to the cmake binary])dnl
if test "x$ac_cv_env_CMAKE_BINARY_set" != "xset"; then
AC_PATH_TOOL([CMAKE_BINARY], [cmake])dnl
fi
])dnl
# $1: package name
# $2: language (e.g. C/CXX/Fortran)
# $3: The compiler ID, defaults to GNU.
# Possible values are: GNU, Intel, Clang, SunPro, HP, XL, VisualAge, PGI,
# PathScale, Cray, SCO, MSVC, LCC
# $4: optional extra arguments to cmake, e.g. "-DCMAKE_SIZEOF_VOID_P=8"
# $5: optional path to cmake binary
AC_DEFUN([CMAKE_FIND_PACKAGE], [
AC_REQUIRE([CMAKE_FIND_BINARY])dnl
AC_ARG_VAR([$1][_][$2][FLAGS], [$2 compiler flags for $1. This overrides the cmake output])dnl
AC_ARG_VAR([$1][_LIBS], [linker flags for $1. This overrides the cmake output])dnl
failed=false
AC_MSG_CHECKING([for $1])
if test -z "${$1[]_$2[]FLAGS}"; then
$1[]_$2[]FLAGS=`$CMAKE_BINARY --find-package "-DNAME=$1" "-DCOMPILER_ID=m4_default([$3], [GNU])" "-DLANGUAGE=$2" -DMODE=COMPILE $4` || failed=true
fi
if test -z "${$1[]_LIBS}"; then
$1[]_LIBS=`$CMAKE_BINARY --find-package "-DNAME=$1" "-DCOMPILER_ID=m4_default([$3], [GNU])" "-DLANGUAGE=$2" -DMODE=LINK $4` || failed=true
fi
if $failed; then
unset $1[]_$2[]FLAGS
unset $1[]_LIBS
AC_MSG_RESULT([no])
$6
else
AC_MSG_RESULT([yes])
$5
fi[]dnl
])

12
cmake/share/applications/cmake-gui.desktop Normal file
View File

@ -0,0 +1,12 @@
[Desktop Entry]
Version=1.0
Name=CMake
Comment=Cross-platform buildsystem
Exec=cmake-gui %f
Icon=CMakeSetup
Terminal=false
X-MultipleArgs=false
Type=Application
Categories=Development;Building;
StartupNotify=true
MimeType=application/x-cmakecache;

216
cmake/share/bash-completion/completions/cmake Normal file
View File

@ -0,0 +1,216 @@
# bash completion for cmake(1) -*- shell-script -*-
_cmake()
{
local is_old_completion=false
local is_init_completion=false
local cur prev words cword split was_split
if type -t _comp_initialize >/dev/null; then
_comp_initialize -s || return
elif type -t _init_completion >/dev/null; then
_init_completion -s || return
is_init_completion=true
else
# manual initialization for older bash completion versions
COMPREPLY=()
cur="${COMP_WORDS[COMP_CWORD]}"
prev="${COMP_WORDS[COMP_CWORD-1]}"
is_old_completion=true
split=false
fi
# Workaround for options like -DCMAKE_BUILD_TYPE=Release
local prefix=
if [[ $cur == -D* ]]; then
prev=-D
prefix=-D
cur="${cur#-D}"
elif [[ $cur == -U* ]]; then
prev=-U
prefix=-U
cur="${cur#-U}"
fi
case "$prev" in
-D)
if [[ $cur == *=* ]]; then
# complete values for variables
local var type value
var="${cur%%[:=]*}"
value="${cur#*=}"
if [[ $cur == CMAKE_BUILD_TYPE* ]]; then # most widely used case
COMPREPLY=( $( compgen -W 'Debug Release RelWithDebInfo
MinSizeRel' -- "$value" ) )
return
fi
if [[ $cur == *:* ]]; then
type="${cur#*:}"
type="${type%%=*}"
else # get type from cache if it's not set explicitly
type=$( cmake -LA -N 2>/dev/null | grep "$var:" \
2>/dev/null )
type="${type#*:}"
type="${type%%=*}"
fi
case "$type" in
FILEPATH)
cur="$value"
_filedir
return
;;
PATH)
cur="$value"
_filedir -d
return
;;
BOOL)
COMPREPLY=( $( compgen -W 'ON OFF TRUE FALSE' -- \
"$value" ) )
return
;;
STRING|INTERNAL)
# no completion available
return
;;
esac
elif [[ $cur == *:* ]]; then
# complete types
local type="${cur#*:}"
COMPREPLY=( $( compgen -W 'FILEPATH PATH STRING BOOL INTERNAL'\
-S = -- "$type" ) )
compopt -o nospace
else
# complete variable names
COMPREPLY=( $( compgen -W '$( cmake -LA -N 2>/dev/null |
tail -n +2 | cut -f1 -d: )' -P "$prefix" -- "$cur" ) )
compopt -o nospace
fi
return
;;
-U)
COMPREPLY=( $( compgen -W '$( cmake -LA -N | tail -n +2 |
cut -f1 -d: )' -P "$prefix" -- "$cur" ) )
return
;;
esac
if $is_old_completion; then
_split_longopt && split=true
fi
case "$prev" in
-C|-P|--graphviz|--system-information)
_filedir
return
;;
--build)
# Seed the reply with non-directory arguments that we know are
# allowed to follow --build. _filedir will then prepend any valid
# directory matches to these.
COMPREPLY=( $( compgen -W "--preset --list-presets" -- "$cur" ) )
_filedir -d
return
;;
--install|--open)
_filedir -d
return
;;
-E)
COMPREPLY=( $( compgen -W "$( cmake -E help |& sed -n \
'/^ [^ ]/{s|^ \([^ ]\{1,\}\) .*$|\1|;p}' 2>/dev/null )" \
-- "$cur" ) )
return
;;
-G)
local IFS=$'\n'
local quoted
printf -v quoted %q "$cur"
COMPREPLY=( $( compgen -W '$( cmake --help 2>/dev/null | sed -n \
-e "1,/^Generators/d" \
-e "/^ *[^ =]/{s|^ *\([^=]*[^ =]\).*$|\1|;s| |\\\\ |g;p}" \
2>/dev/null )' -- "$quoted" ) )
return
;;
--loglevel)
COMPREPLY=( $(compgen -W 'error warning notice status verbose debug trace' -- $cur ) )
;;
--help-command)
COMPREPLY=( $( compgen -W '$( cmake --help-command-list 2>/dev/null|
grep -v "^cmake version " )' -- "$cur" ) )
return
;;
--help-manual)
COMPREPLY=( $( compgen -W '$( cmake --help-manual-list 2>/dev/null|
grep -v "^cmake version " | sed -e "s/([0-9])$//" )' -- "$cur" ) )
return
;;
--help-module)
COMPREPLY=( $( compgen -W '$( cmake --help-module-list 2>/dev/null|
grep -v "^cmake version " )' -- "$cur" ) )
return
;;
--help-policy)
COMPREPLY=( $( compgen -W '$( cmake --help-policy-list 2>/dev/null |
grep -v "^cmake version " )' -- "$cur" ) )
return
;;
--help-property)
COMPREPLY=( $( compgen -W '$( cmake --help-property-list \
2>/dev/null | grep -v "^cmake version " )' -- "$cur" ) )
return
;;
--help-variable)
COMPREPLY=( $( compgen -W '$( cmake --help-variable-list \
2>/dev/null | grep -v "^cmake version " )' -- "$cur" ) )
return
;;
--list-presets)
local IFS=$'\n'
local quoted
printf -v quoted %q "$cur"
if [[ ! "${IFS}${COMP_WORDS[*]}${IFS}" =~ "${IFS}--build${IFS}" ]]; then
COMPREPLY=( $( compgen -W "configure${IFS}build${IFS}test${IFS}all" -- "$quoted" ) )
fi
return
;;
--preset)
local IFS=$'\n'
local quoted
printf -v quoted %q "$cur"
local build_or_configure="configure"
if [[ "${IFS}${COMP_WORDS[*]}${IFS}" =~ "${IFS}--build${IFS}" ]]; then
build_or_configure="build"
fi
local presets=$( cmake --list-presets="$build_or_configure" 2>/dev/null |
grep -o "^ \".*\"" | sed \
-e "s/^ //g" \
-e "s/\"//g" \
-e 's/ /\\\\ /g' )
COMPREPLY=( $( compgen -W "$presets" -- "$quoted" ) )
return
;;
esac
if ($is_old_completion || $is_init_completion); then
$split && return
else
[[ $was_split ]] && return
fi
if [[ "$cur" == -* ]]; then
COMPREPLY=( $(compgen -W '$( _parse_help "$1" --help )' -- ${cur}) )
[[ $COMPREPLY == *= ]] && compopt -o nospace
[[ $COMPREPLY ]] && return
fi
_filedir
} &&
complete -F _cmake cmake
# ex: ts=4 sw=4 et filetype=sh

90
cmake/share/bash-completion/completions/cpack Normal file
View File

@ -0,0 +1,90 @@
# bash completion for cpack(1) -*- shell-script -*-
_cpack()
{
local cur prev words cword
if type -t _comp_initialize >/dev/null; then
_comp_initialize -n = || return
elif type -t _init_completion >/dev/null; then
_init_completion -n = || return
else
# manual initialization for older bash completion versions
COMPREPLY=()
cur="${COMP_WORDS[COMP_CWORD]}"
prev="${COMP_WORDS[COMP_CWORD-1]}"
fi
case "$prev" in
-G)
COMPREPLY=( $( compgen -W '$( cpack --help 2>/dev/null |
sed -e "1,/^Generators/d" -e "s|^ *\([^ ]*\) .*$|\1|" \
2>/dev/null )' -- "$cur" ) )
return
;;
-C)
COMPREPLY=( $( compgen -W 'Debug Release RelWithDebInfo
MinSizeRel' -- "$cur" ) )
return
;;
-D)
[[ $cur == *=* ]] && return # no completion for values
COMPREPLY=( $( compgen -W '$( cpack --help-variable-list \
2>/dev/null | grep -v "^cpack version " )' -S = -- "$cur" ) )
compopt -o nospace
return
;;
-P|-R|--vendor)
# argument required but no completions available
return
;;
-B)
_filedir -d
return
;;
--config)
_filedir
return
;;
--help-command)
COMPREPLY=( $( compgen -W '$( cpack --help-command-list 2>/dev/null|
grep -v "^cpack version " )' -- "$cur" ) )
return
;;
--help-manual)
COMPREPLY=( $( compgen -W '$( cpack --help-manual-list 2>/dev/null|
grep -v "^cpack version " | sed -e "s/([0-9])$//" )' -- "$cur" ) )
return
;;
--help-module)
COMPREPLY=( $( compgen -W '$( cpack --help-module-list 2>/dev/null|
grep -v "^cpack version " )' -- "$cur" ) )
return
;;
--help-policy)
COMPREPLY=( $( compgen -W '$( cpack --help-policy-list 2>/dev/null |
grep -v "^cpack version " )' -- "$cur" ) )
return
;;
--help-property)
COMPREPLY=( $( compgen -W '$( cpack --help-property-list \
2>/dev/null | grep -v "^cpack version " )' -- "$cur" ) )
return
;;
--help-variable)
COMPREPLY=( $( compgen -W '$( cpack --help-variable-list \
2>/dev/null | grep -v "^cpack version " )' -- "$cur" ) )
return
;;
esac
if [[ "$cur" == -* ]]; then
COMPREPLY=( $(compgen -W '$( _parse_help "$1" --help )' -- ${cur}) )
[[ $COMPREPLY == *= ]] && compopt -o nospace
[[ $COMPREPLY ]] && return
fi
_filedir
} &&
complete -F _cpack cpack
# ex: ts=4 sw=4 et filetype=sh

131
cmake/share/bash-completion/completions/ctest Normal file
View File

@ -0,0 +1,131 @@
# bash completion for ctest(1) -*- shell-script -*-
_ctest()
{
local cur prev words cword
if type -t _comp_initialize >/dev/null; then
_comp_initialize -n = || return
elif type -t _init_completion >/dev/null; then
_init_completion -n = || return
else
# manual initialization for older bash completion versions
COMPREPLY=()
cur="${COMP_WORDS[COMP_CWORD]}"
prev="${COMP_WORDS[COMP_CWORD-1]}"
fi
case "$prev" in
-C|--build-config)
COMPREPLY=( $( compgen -W 'Debug Release RelWithDebInfo
MinSizeRel' -- "$cur" ) )
return
;;
-j|--parallel)
COMPREPLY=( $( compgen -W "{1..$(( $(_ncpus)*2 ))}" -- "$cur" ) )
return
;;
-O|--output-log|-A|--add-notes|--extra-submit)
_filedir
return
;;
-L|--label-regex|-LE|--label-exclude)
COMPREPLY=( $( compgen -W '$( ctest --print-labels 2>/dev/null |
grep "^ " 2>/dev/null | cut -d" " -f 3 )' -- "$cur" ) )
return
;;
--track|-I|--tests-information|--max-width|--timeout|--stop-time)
# argument required but no completions available
return
;;
-R|--tests-regex|-E|--exclude-regex)
COMPREPLY=( $( compgen -W '$( ctest -N 2>/dev/null |
grep "^ Test" 2>/dev/null | cut -d: -f 2 )' -- "$cur" ) )
return
;;
-D|--dashboard)
if [[ $cur == @(Experimental|Nightly|Continuous)* ]]; then
local model action
action=${cur#@(Experimental|Nightly|Continuous)}
model=${cur%"$action"}
COMPREPLY=( $( compgen -W 'Start Update Configure Build Test
Coverage Submit MemCheck' -P "$model" -- "$action" ) )
else
COMPREPLY=( $( compgen -W 'Experimental Nightly Continuous' \
-- "$cur" ) )
compopt -o nospace
fi
return
;;
-M|--test-model)
COMPREPLY=( $( compgen -W 'Experimental Nightly Continuous' -- \
"$cur" ) )
return
;;
-T|--test-action)
COMPREPLY=( $( compgen -W 'Start Update Configure Build Test
Coverage Submit MemCheck' -- "$cur" ) )
return
;;
-S|--script|-SP|--script-new-process)
_filedir '@(cmake|ctest)'
return
;;
--interactive-debug-mode)
COMPREPLY=( $( compgen -W '0 1' -- "$cur" ) )
return
;;
--help-command)
COMPREPLY=( $( compgen -W '$( ctest --help-command-list 2>/dev/null|
grep -v "^ctest version " )' -- "$cur" ) )
return
;;
--help-manual)
COMPREPLY=( $( compgen -W '$( ctest --help-manual-list 2>/dev/null|
grep -v "^ctest version " | sed -e "s/([0-9])$//" )' -- "$cur" ) )
return
;;
--help-module)
COMPREPLY=( $( compgen -W '$( ctest --help-module-list 2>/dev/null|
grep -v "^ctest version " )' -- "$cur" ) )
return
;;
--help-policy)
COMPREPLY=( $( compgen -W '$( ctest --help-policy-list 2>/dev/null |
grep -v "^ctest version " )' -- "$cur" ) )
return
;;
--help-property)
COMPREPLY=( $( compgen -W '$( ctest --help-property-list \
2>/dev/null | grep -v "^ctest version " )' -- "$cur" ) )
return
;;
--help-variable)
COMPREPLY=( $( compgen -W '$( ctest --help-variable-list \
2>/dev/null | grep -v "^ctest version " )' -- "$cur" ) )
return
;;
--preset)
local IFS=$'\n'
local quoted
printf -v quoted %q "$cur"
COMPREPLY=( $( compgen -W '$( ctest --list-presets 2>/dev/null |
grep -o "^ \".*\"" | sed \
-e "s/^ //g" \
-e "s/\"//g" \
-e "s/ /\\\\ /g" )' -- "$quoted" ) )
return
;;
esac
if [[ "$cur" == -* ]]; then
COMPREPLY=( $(compgen -W '$( _parse_help "$1" --help )' -- ${cur}) )
[[ $COMPREPLY == *= ]] && compopt -o nospace
[[ $COMPREPLY ]] && return
fi
_filedir
} &&
complete -F _ctest ctest
# ex: ts=4 sw=4 et filetype=sh

15
cmake/share/cmake-3.30/Help/command/DEPRECATED_POLICY_VERSIONS.txt Normal file
View File

@ -0,0 +1,15 @@
.. versionchanged:: 3.27
Compatibility with versions of CMake older than 3.5 is deprecated.
Calls to :command:`cmake_minimum_required(VERSION)` or
:command:`cmake_policy(VERSION)` that do not specify at least
3.5 as their policy version (optionally via ``...<max>``)
will produce a deprecation warning in CMake 3.27 and above.
.. versionchanged:: 3.19
Compatibility with versions of CMake older than 2.8.12 is deprecated.
Calls to :command:`cmake_minimum_required(VERSION)` or
:command:`cmake_policy(VERSION)` that do not specify at least
2.8.12 as their policy version (optionally via ``...<max>``)
will produce a deprecation warning in CMake 3.19 and above.

12
cmake/share/cmake-3.30/Help/command/DEVICE_LINK_OPTIONS.txt Normal file
View File

@ -0,0 +1,12 @@
Host And Device Specific Link Options
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
.. versionadded:: 3.18
When a device link step is involved, which is controlled by
:prop_tgt:`CUDA_SEPARABLE_COMPILATION` and
:prop_tgt:`CUDA_RESOLVE_DEVICE_SYMBOLS` properties and policy :policy:`CMP0105`,
the raw options will be delivered to the host and device link steps (wrapped in
``-Xcompiler`` or equivalent for device link). Options wrapped with
:genex:`$<DEVICE_LINK:...>` generator expression will be used
only for the device link step. Options wrapped with :genex:`$<HOST_LINK:...>`
generator expression will be used only for the host link step.

253
cmake/share/cmake-3.30/Help/command/FIND_XXX.txt Normal file
View File

@ -0,0 +1,253 @@
A short-hand signature is:
.. parsed-literal::
|FIND_XXX| (<VAR> name1 [path1 path2 ...])
The general signature is:
.. parsed-literal::
|FIND_XXX| (
<VAR>
name | |NAMES|
[HINTS [path | ENV var]... ]
[PATHS [path | ENV var]... ]
[REGISTRY_VIEW (64|32|64_32|32_64|HOST|TARGET|BOTH)]
[PATH_SUFFIXES suffix1 [suffix2 ...]]
[VALIDATOR function]
[DOC "cache documentation string"]
[NO_CACHE]
[REQUIRED]
[NO_DEFAULT_PATH]
[NO_PACKAGE_ROOT_PATH]
[NO_CMAKE_PATH]
[NO_CMAKE_ENVIRONMENT_PATH]
[NO_SYSTEM_ENVIRONMENT_PATH]
[NO_CMAKE_SYSTEM_PATH]
[NO_CMAKE_INSTALL_PREFIX]
[CMAKE_FIND_ROOT_PATH_BOTH |
ONLY_CMAKE_FIND_ROOT_PATH |
NO_CMAKE_FIND_ROOT_PATH]
)
This command is used to find a |SEARCH_XXX_DESC|.
A cache entry, or a normal variable if ``NO_CACHE`` is specified,
named by ``<VAR>`` is created to store the result of this command.
If the |SEARCH_XXX| is found the result is stored in the variable
and the search will not be repeated unless the variable is cleared.
If nothing is found, the result will be ``<VAR>-NOTFOUND``.
Options include:
``NAMES``
Specify one or more possible names for the |SEARCH_XXX|.
When using this to specify names with and without a version
suffix, we recommend specifying the unversioned name first
so that locally-built packages can be found before those
provided by distributions.
``HINTS``, ``PATHS``
Specify directories to search in addition to the default locations.
The ``ENV var`` sub-option reads paths from a system environment
variable.
.. versionchanged:: 3.24
On ``Windows`` platform, it is possible to include registry queries as part
of the directories, using a :ref:`dedicated syntax <Find Using Windows Registry>`.
Such specifications will be ignored on all other platforms.
``REGISTRY_VIEW``
.. versionadded:: 3.24
.. include:: FIND_XXX_REGISTRY_VIEW.txt
``PATH_SUFFIXES``
Specify additional subdirectories to check below each directory
location otherwise considered.
``VALIDATOR``
.. versionadded:: 3.25
Specify a :command:`function` to be called for each candidate item found
(a :command:`macro` cannot be provided, that will result in an error).
Two arguments will be passed to the validator function: the name of a
result variable, and the absolute path to the candidate item. The item
will be accepted and the search will end unless the function sets the
value in the result variable to false in the calling scope. The result
variable will hold a true value when the validator function is entered.
.. parsed-literal::
function(my_check validator_result_var item)
if(NOT item MATCHES ...)
set(${validator_result_var} FALSE PARENT_SCOPE)
endif()
endfunction()
|FIND_XXX| (result NAMES ... VALIDATOR my_check)
Note that if a cached result is used, the search is skipped and any
``VALIDATOR`` is ignored. The cached result is not required to pass the
validation function.
``DOC``
Specify the documentation string for the ``<VAR>`` cache entry.
``NO_CACHE``
.. versionadded:: 3.21
The result of the search will be stored in a normal variable rather than
a cache entry.
.. note::
If the variable is already set before the call (as a normal or cache
variable) then the search will not occur.
.. warning::
This option should be used with caution because it can greatly increase
the cost of repeated configure steps.
``REQUIRED``
.. versionadded:: 3.18
Stop processing with an error message if nothing is found, otherwise
the search will be attempted again the next time |FIND_XXX| is invoked
with the same variable.
If ``NO_DEFAULT_PATH`` is specified, then no additional paths are
added to the search.
If ``NO_DEFAULT_PATH`` is not specified, the search process is as follows:
.. |FIND_PACKAGE_ROOT_PREFIX_PATH_XXX_SUBDIR| replace::
|prefix_XXX_SUBDIR| for each ``<prefix>`` in the
:variable:`<PackageName>_ROOT` CMake variable and the
:envvar:`<PackageName>_ROOT` environment variable if
called from within a find module loaded by
:command:`find_package(<PackageName>)`
.. |CMAKE_PREFIX_PATH_XXX_SUBDIR| replace::
|prefix_XXX_SUBDIR| for each ``<prefix>`` in :variable:`CMAKE_PREFIX_PATH`
.. |ENV_CMAKE_PREFIX_PATH_XXX_SUBDIR| replace::
|prefix_XXX_SUBDIR| for each ``<prefix>`` in :envvar:`CMAKE_PREFIX_PATH`
.. |SYSTEM_ENVIRONMENT_PREFIX_PATH_XXX_SUBDIR| replace::
|prefix_XXX_SUBDIR| for each ``<prefix>/[s]bin`` in ``PATH``, and
|entry_XXX_SUBDIR| for other entries in ``PATH``
.. |CMAKE_SYSTEM_PREFIX_PATH_XXX_SUBDIR| replace::
|prefix_XXX_SUBDIR| for each ``<prefix>`` in
:variable:`CMAKE_SYSTEM_PREFIX_PATH`
1. If called from within a find module or any other script loaded by a call to
:command:`find_package(<PackageName>)`, search prefixes unique to the
current package being found. See policy :policy:`CMP0074`.
.. versionadded:: 3.12
Specifically, search paths specified by the following variables, in order:
a. :variable:`<PackageName>_ROOT` CMake variable,
where ``<PackageName>`` is the case-preserved package name.
b. :variable:`<PACKAGENAME>_ROOT` CMake variable,
where ``<PACKAGENAME>`` is the upper-cased package name.
See policy :policy:`CMP0144`.
.. versionadded:: 3.27
c. :envvar:`<PackageName>_ROOT` environment variable,
where ``<PackageName>`` is the case-preserved package name.
d. :envvar:`<PACKAGENAME>_ROOT` environment variable,
where ``<PACKAGENAME>`` is the upper-cased package name.
See policy :policy:`CMP0144`.
.. versionadded:: 3.27
The package root variables are maintained as a stack, so if called from
nested find modules or config packages, root paths from the parent's find
module or config package will be searched after paths from the current
module or package. In other words, the search order would be
``<CurrentPackage>_ROOT``, ``ENV{<CurrentPackage>_ROOT}``,
``<ParentPackage>_ROOT``, ``ENV{<ParentPackage>_ROOT}``, etc.
This can be skipped if ``NO_PACKAGE_ROOT_PATH`` is passed or by setting
the :variable:`CMAKE_FIND_USE_PACKAGE_ROOT_PATH` to ``FALSE``.
* |FIND_PACKAGE_ROOT_PREFIX_PATH_XXX|
2. Search paths specified in cmake-specific cache variables.
These are intended to be used on the command line with a ``-DVAR=value``.
The values are interpreted as :ref:`semicolon-separated lists <CMake Language Lists>`.
This can be skipped if ``NO_CMAKE_PATH`` is passed or by setting the
:variable:`CMAKE_FIND_USE_CMAKE_PATH` to ``FALSE``.
* |CMAKE_PREFIX_PATH_XXX|
* |CMAKE_XXX_PATH|
* |CMAKE_XXX_MAC_PATH|
3. Search paths specified in cmake-specific environment variables.
These are intended to be set in the user's shell configuration,
and therefore use the host's native path separator
(``;`` on Windows and ``:`` on UNIX).
This can be skipped if ``NO_CMAKE_ENVIRONMENT_PATH`` is passed or
by setting the :variable:`CMAKE_FIND_USE_CMAKE_ENVIRONMENT_PATH` to ``FALSE``.
* |ENV_CMAKE_PREFIX_PATH_XXX|
* |ENV_CMAKE_XXX_PATH|
* |ENV_CMAKE_XXX_MAC_PATH|
4. Search the paths specified by the ``HINTS`` option.
These should be paths computed by system introspection, such as a
hint provided by the location of another item already found.
Hard-coded guesses should be specified with the ``PATHS`` option.
5. Search the standard system environment variables.
This can be skipped if ``NO_SYSTEM_ENVIRONMENT_PATH`` is passed or by
setting the :variable:`CMAKE_FIND_USE_SYSTEM_ENVIRONMENT_PATH` to ``FALSE``.
* |SYSTEM_ENVIRONMENT_PATH_XXX|
|SYSTEM_ENVIRONMENT_PATH_WINDOWS_XXX|
6. Search cmake variables defined in the Platform files
for the current system. The searching of ``CMAKE_INSTALL_PREFIX`` and
``CMAKE_STAGING_PREFIX`` can be
skipped if ``NO_CMAKE_INSTALL_PREFIX`` is passed or by setting the
:variable:`CMAKE_FIND_USE_INSTALL_PREFIX` to ``FALSE``. All these locations
can be skipped if ``NO_CMAKE_SYSTEM_PATH`` is passed or by setting the
:variable:`CMAKE_FIND_USE_CMAKE_SYSTEM_PATH` to ``FALSE``.
* |CMAKE_SYSTEM_PREFIX_PATH_XXX|
* |CMAKE_SYSTEM_XXX_PATH|
* |CMAKE_SYSTEM_XXX_MAC_PATH|
The platform paths that these variables contain are locations that
typically include installed software. An example being ``/usr/local`` for
UNIX based platforms.
7. Search the paths specified by the PATHS option
or in the short-hand version of the command.
These are typically hard-coded guesses.
The :variable:`CMAKE_IGNORE_PATH`, :variable:`CMAKE_IGNORE_PREFIX_PATH`,
:variable:`CMAKE_SYSTEM_IGNORE_PATH` and
:variable:`CMAKE_SYSTEM_IGNORE_PREFIX_PATH` variables can also cause some
of the above locations to be ignored.
.. versionadded:: 3.16
Added ``CMAKE_FIND_USE_<CATEGORY>_PATH`` variables to globally disable
various search locations.
.. |FIND_ARGS_XXX| replace:: <VAR> NAMES name
On macOS the :variable:`CMAKE_FIND_FRAMEWORK` and
:variable:`CMAKE_FIND_APPBUNDLE` variables determine the order of
preference between Apple-style and unix-style package components.
.. include:: FIND_XXX_ROOT.txt
.. include:: FIND_XXX_ORDER.txt

12
cmake/share/cmake-3.30/Help/command/FIND_XXX_ORDER.txt Normal file
View File

@ -0,0 +1,12 @@
The default search order is designed to be most-specific to
least-specific for common use cases.
Projects may override the order by simply calling the command
multiple times and using the ``NO_*`` options:
.. parsed-literal::
|FIND_XXX| (|FIND_ARGS_XXX| PATHS paths... NO_DEFAULT_PATH)
|FIND_XXX| (|FIND_ARGS_XXX|)
Once one of the calls succeeds the result variable will be set
and stored in the cache so that no call will search again.

41
cmake/share/cmake-3.30/Help/command/FIND_XXX_REGISTRY_VIEW.txt Normal file
View File

@ -0,0 +1,41 @@
Specify which registry views must be queried. This option is only meaningful
on ``Windows`` platforms and will be ignored on other ones. When not
specified, the |FIND_XXX_REGISTRY_VIEW_DEFAULT| view is used when the
:policy:`CMP0134` policy is ``NEW``. Refer to :policy:`CMP0134` for the
default view when the policy is ``OLD``.
``64``
Query the 64-bit registry. On 32-bit Windows, it always returns the string
``/REGISTRY-NOTFOUND``.
``32``
Query the 32-bit registry.
``64_32``
Query both views (``64`` and ``32``) and generate a path for each.
``32_64``
Query both views (``32`` and ``64``) and generate a path for each.
``HOST``
Query the registry matching the architecture of the host: ``64`` on 64-bit
Windows and ``32`` on 32-bit Windows.
``TARGET``
Query the registry matching the architecture specified by the
:variable:`CMAKE_SIZEOF_VOID_P` variable. If not defined, fall back to
``HOST`` view.
``BOTH``
Query both views (``32`` and ``64``). The order depends on the following
rules: If the :variable:`CMAKE_SIZEOF_VOID_P` variable is defined, use the
following view depending on the content of this variable:
* ``8``: ``64_32``
* ``4``: ``32_64``
If the :variable:`CMAKE_SIZEOF_VOID_P` variable is not defined, rely on the
architecture of the host:
* 64-bit: ``64_32``
* 32-bit: ``32``

29
cmake/share/cmake-3.30/Help/command/FIND_XXX_ROOT.txt Normal file
View File

@ -0,0 +1,29 @@
The CMake variable :variable:`CMAKE_FIND_ROOT_PATH` specifies one or more
directories to be prepended to all other search directories. This
effectively "re-roots" the entire search under given locations.
Paths which are descendants of the :variable:`CMAKE_STAGING_PREFIX` are excluded
from this re-rooting, because that variable is always a path on the host system.
By default the :variable:`CMAKE_FIND_ROOT_PATH` is empty.
The :variable:`CMAKE_SYSROOT` variable can also be used to specify exactly one
directory to use as a prefix. Setting :variable:`CMAKE_SYSROOT` also has other
effects. See the documentation for that variable for more.
These variables are especially useful when cross-compiling to
point to the root directory of the target environment and CMake will
search there too. By default at first the directories listed in
:variable:`CMAKE_FIND_ROOT_PATH` are searched, then the :variable:`CMAKE_SYSROOT`
directory is searched, and then the non-rooted directories will be
searched. The default behavior can be adjusted by setting
|CMAKE_FIND_ROOT_PATH_MODE_XXX|. This behavior can be manually
overridden on a per-call basis using options:
``CMAKE_FIND_ROOT_PATH_BOTH``
Search in the order described above.
``NO_CMAKE_FIND_ROOT_PATH``
Do not use the :variable:`CMAKE_FIND_ROOT_PATH` variable.
``ONLY_CMAKE_FIND_ROOT_PATH``
Search only the re-rooted directories and directories below
:variable:`CMAKE_STAGING_PREFIX`.

6
cmake/share/cmake-3.30/Help/command/GENEX_NOTE.txt Normal file
View File

@ -0,0 +1,6 @@
.. |more_see_also| replace:: See the :manual:`cmake-buildsystem(7)` manual
for more on defining buildsystem properties.
Arguments to |command_name| may use generator expressions
with the syntax ``$<...>``. See the :manual:`cmake-generator-expressions(7)`
manual for available expressions. |more_see_also|

25
cmake/share/cmake-3.30/Help/command/LINK_OPTIONS_LINKER.txt Normal file
View File

@ -0,0 +1,25 @@
Handling Compiler Driver Differences
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
To pass options to the linker tool, each compiler driver has its own syntax.
The ``LINKER:`` prefix and ``,`` separator can be used to specify, in a portable
way, options to pass to the linker tool. ``LINKER:`` is replaced by the
appropriate driver option and ``,`` by the appropriate driver separator.
The driver prefix and driver separator are given by the values of the
:variable:`CMAKE_<LANG>_LINKER_WRAPPER_FLAG` and
:variable:`CMAKE_<LANG>_LINKER_WRAPPER_FLAG_SEP` variables.
For example, ``"LINKER:-z,defs"`` becomes ``-Xlinker -z -Xlinker defs`` for
``Clang`` and ``-Wl,-z,defs`` for ``GNU GCC``.
The ``LINKER:`` prefix can be specified as part of a ``SHELL:`` prefix
expression.
The ``LINKER:`` prefix supports, as an alternative syntax, specification of
arguments using the ``SHELL:`` prefix and space as separator. The previous
example then becomes ``"LINKER:SHELL:-z defs"``.
.. note::
Specifying the ``SHELL:`` prefix anywhere other than at the beginning of the
``LINKER:`` prefix is not supported.

15
cmake/share/cmake-3.30/Help/command/OPTIONS_SHELL.txt Normal file
View File

@ -0,0 +1,15 @@
Option De-duplication
^^^^^^^^^^^^^^^^^^^^^
The final set of options used for a target is constructed by
accumulating options from the current target and the usage requirements of
its dependencies. The set of options is de-duplicated to avoid repetition.
.. versionadded:: 3.12
While beneficial for individual options, the de-duplication step can break
up option groups. For example, ``-option A -option B`` becomes
``-option A B``. One may specify a group of options using shell-like
quoting along with a ``SHELL:`` prefix. The ``SHELL:`` prefix is dropped,
and the rest of the option string is parsed using the
:command:`separate_arguments` ``UNIX_COMMAND`` mode. For example,
``"SHELL:-option A" "SHELL:-option B"`` becomes ``-option A -option B``.

25
cmake/share/cmake-3.30/Help/command/SUPPORTED_LANGUAGES.txt Normal file
View File

@ -0,0 +1,25 @@
Supported languages are ``C``, ``CXX`` (i.e. C++), ``CSharp`` (i.e. C#), ``CUDA``,
``OBJC`` (i.e. Objective-C), ``OBJCXX`` (i.e. Objective-C++), ``Fortran``, ``HIP``,
``ISPC``, ``Swift``, ``ASM``, ``ASM_NASM``, ``ASM_MARMASM``, ``ASM_MASM``, and ``ASM-ATT``.
.. versionadded:: 3.8
Added ``CSharp`` and ``CUDA`` support.
.. versionadded:: 3.15
Added ``Swift`` support.
.. versionadded:: 3.16
Added ``OBJC`` and ``OBJCXX`` support.
.. versionadded:: 3.18
Added ``ISPC`` support.
.. versionadded:: 3.21
Added ``HIP`` support.
.. versionadded:: 3.26
Added ``ASM_MARMASM`` support.
If enabling ``ASM``, list it last so that CMake can check whether
compilers for other languages like ``C`` work for assembly too.

9
cmake/share/cmake-3.30/Help/command/UNSET_NOTE.txt Normal file
View File

@ -0,0 +1,9 @@
.. note::
When evaluating :ref:`Variable References` of the form ``${VAR}``, CMake
first searches for a normal variable with that name. If no such normal
variable exists, CMake will then search for a cache entry with that name.
Because of this, **unsetting a normal variable can expose a cache variable
that was previously hidden**. To force a variable reference of the form
``${VAR}`` to return an empty string, use ``set(<variable> "")``, which
clears the normal variable but leaves it defined.

33
cmake/share/cmake-3.30/Help/command/add_compile_definitions.rst Normal file
View File

@ -0,0 +1,33 @@
add_compile_definitions
-----------------------
.. versionadded:: 3.12
Add preprocessor definitions to the compilation of source files.
.. code-block:: cmake
add_compile_definitions(<definition> ...)
Adds preprocessor definitions to the compiler command line.
The preprocessor definitions are added to the :prop_dir:`COMPILE_DEFINITIONS`
directory property for the current ``CMakeLists`` file. They are also added to
the :prop_tgt:`COMPILE_DEFINITIONS` target property for each target in the
current ``CMakeLists`` file.
Definitions are specified using the syntax ``VAR`` or ``VAR=value``.
Function-style definitions are not supported. CMake will automatically
escape the value correctly for the native build system (note that CMake
language syntax may require escapes to specify some values).
.. versionadded:: 3.26
Any leading ``-D`` on an item will be removed.
.. |command_name| replace:: ``add_compile_definitions``
.. include:: GENEX_NOTE.txt
See Also
^^^^^^^^
* The command :command:`target_compile_definitions` adds target-specific definitions.

67
cmake/share/cmake-3.30/Help/command/add_compile_options.rst Normal file
View File

@ -0,0 +1,67 @@
add_compile_options
-------------------
Add options to the compilation of source files.
.. code-block:: cmake
add_compile_options(<option> ...)
Adds options to the :prop_dir:`COMPILE_OPTIONS` directory property.
These options are used when compiling targets from the current
directory and below.
.. note::
These options are not used when linking.
See the :command:`add_link_options` command for that.
Arguments
^^^^^^^^^
.. |command_name| replace:: ``add_compile_options``
.. include:: GENEX_NOTE.txt
.. include:: OPTIONS_SHELL.txt
Example
^^^^^^^
Since different compilers support different options, a typical use of
this command is in a compiler-specific conditional clause:
.. code-block:: cmake
if (MSVC)
# warning level 4
add_compile_options(/W4)
else()
# additional warnings
add_compile_options(-Wall -Wextra -Wpedantic)
endif()
To set per-language options, use the :genex:`$<COMPILE_LANGUAGE>`
or :genex:`$<COMPILE_LANGUAGE:languages>` generator expressions.
See Also
^^^^^^^^
* This command can be used to add any options. However, for
adding preprocessor definitions and include directories it is recommended
to use the more specific commands :command:`add_compile_definitions`
and :command:`include_directories`.
* The command :command:`target_compile_options` adds target-specific options.
* This command adds compile options for all languages.
Use the :genex:`COMPILE_LANGUAGE` generator expression to specify
per-language compile options.
* The source file property :prop_sf:`COMPILE_OPTIONS` adds options to one
source file.
* :command:`add_link_options` adds options for linking.
* :variable:`CMAKE_<LANG>_FLAGS` and :variable:`CMAKE_<LANG>_FLAGS_<CONFIG>`
add language-wide flags passed to all invocations of the compiler.
This includes invocations that drive compiling and those that drive linking.

615
cmake/share/cmake-3.30/Help/command/add_custom_command.rst Normal file
View File

@ -0,0 +1,615 @@
add_custom_command
------------------
Add a custom build rule to the generated build system.
There are two main signatures for ``add_custom_command``.
Generating Files
^^^^^^^^^^^^^^^^
The first signature is for adding a custom command to produce an output:
.. code-block:: cmake
add_custom_command(OUTPUT output1 [output2 ...]
COMMAND command1 [ARGS] [args1...]
[COMMAND command2 [ARGS] [args2...] ...]
[MAIN_DEPENDENCY depend]
[DEPENDS [depends...]]
[BYPRODUCTS [files...]]
[IMPLICIT_DEPENDS <lang1> depend1
[<lang2> depend2] ...]
[WORKING_DIRECTORY dir]
[COMMENT comment]
[DEPFILE depfile]
[JOB_POOL job_pool]
[JOB_SERVER_AWARE <bool>]
[VERBATIM] [APPEND] [USES_TERMINAL]
[COMMAND_EXPAND_LISTS]
[DEPENDS_EXPLICIT_ONLY])
This defines a command to generate specified ``OUTPUT`` file(s).
A target created in the same directory (``CMakeLists.txt`` file)
that specifies any output of the custom command as a source file
is given a rule to generate the file using the command at build time.
Do not list the output in more than one independent target that
may build in parallel or the instances of the rule may conflict.
Instead, use the :command:`add_custom_target` command to drive the
command and make the other targets depend on that one. See the
`Example: Generating Files for Multiple Targets`_ below.
The options are:
``APPEND``
Append the ``COMMAND`` and ``DEPENDS`` option values to the custom
command for the first output specified. There must have already
been a previous call to this command with the same output.
If the previous call specified the output via a generator expression,
the output specified by the current call must match in at least one
configuration after evaluating generator expressions. In this case,
the appended commands and dependencies apply to all configurations.
The ``COMMENT``, ``MAIN_DEPENDENCY``, and ``WORKING_DIRECTORY``
options are currently ignored when APPEND is given, but may be
used in the future.
``BYPRODUCTS``
.. versionadded:: 3.2
Specify the files the command is expected to produce but whose
modification time may or may not be newer than the dependencies.
If a byproduct name is a relative path it will be interpreted
relative to the build tree directory corresponding to the
current source directory.
Each byproduct file will be marked with the :prop_sf:`GENERATED`
source file property automatically.
*See policy* :policy:`CMP0058` *for the motivation behind this feature.*
Explicit specification of byproducts is supported by the
:generator:`Ninja` generator to tell the ``ninja`` build tool
how to regenerate byproducts when they are missing. It is
also useful when other build rules (e.g. custom commands)
depend on the byproducts. Ninja requires a build rule for any
generated file on which another rule depends even if there are
order-only dependencies to ensure the byproducts will be
available before their dependents build.
The :ref:`Makefile Generators` will remove ``BYPRODUCTS`` and other
:prop_sf:`GENERATED` files during ``make clean``.
.. versionadded:: 3.20
Arguments to ``BYPRODUCTS`` may use a restricted set of
:manual:`generator expressions <cmake-generator-expressions(7)>`.
:ref:`Target-dependent expressions <Target-Dependent Expressions>`
are not permitted.
.. versionchanged:: 3.28
In targets using :ref:`file sets`, custom command byproducts are now
considered private unless they are listed in a non-private file set.
See policy :policy:`CMP0154`.
``COMMAND``
Specify the command-line(s) to execute at build time.
If more than one ``COMMAND`` is specified they will be executed in order,
but *not* necessarily composed into a stateful shell or batch script.
(To run a full script, use the :command:`configure_file` command or the
:command:`file(GENERATE)` command to create it, and then specify
a ``COMMAND`` to launch it.)
The optional ``ARGS`` argument is for backward compatibility and
will be ignored.
If ``COMMAND`` specifies an executable target name (created by the
:command:`add_executable` command), it will automatically be replaced
by the location of the executable created at build time if either of
the following is true:
* The target is not being cross-compiled (i.e. the
:variable:`CMAKE_CROSSCOMPILING` variable is not set to true).
* .. versionadded:: 3.6
The target is being cross-compiled and an emulator is provided (i.e.
its :prop_tgt:`CROSSCOMPILING_EMULATOR` target property is set).
In this case, the contents of :prop_tgt:`CROSSCOMPILING_EMULATOR` will be
prepended to the command before the location of the target executable.
If neither of the above conditions are met, it is assumed that the
command name is a program to be found on the ``PATH`` at build time.
Arguments to ``COMMAND`` may use
:manual:`generator expressions <cmake-generator-expressions(7)>`.
Use the :genex:`TARGET_FILE` generator expression to refer to the location
of a target later in the command line (i.e. as a command argument rather
than as the command to execute).
Whenever one of the following target based generator expressions are used as
a command to execute or is mentioned in a command argument, a target-level
dependency will be added automatically so that the mentioned target will be
built before any target using this custom command
(see policy :policy:`CMP0112`).
* ``TARGET_FILE``
* ``TARGET_LINKER_FILE``
* ``TARGET_SONAME_FILE``
* ``TARGET_PDB_FILE``
This target-level dependency does NOT add a file-level dependency that would
cause the custom command to re-run whenever the executable is recompiled.
List target names with the ``DEPENDS`` option to add such file-level
dependencies.
``COMMENT``
Display the given message before the commands are executed at
build time.
.. versionadded:: 3.26
Arguments to ``COMMENT`` may use
:manual:`generator expressions <cmake-generator-expressions(7)>`.
``DEPENDS``
Specify files on which the command depends. Each argument is converted
to a dependency as follows:
1. If the argument is the name of a target (created by the
:command:`add_custom_target`, :command:`add_executable`, or
:command:`add_library` command) a target-level dependency is
created to make sure the target is built before any target
using this custom command. Additionally, if the target is an
executable or library, a file-level dependency is created to
cause the custom command to re-run whenever the target is
recompiled.
2. If the argument is an absolute path, a file-level dependency
is created on that path.
3. If the argument is the name of a source file that has been
added to a target or on which a source file property has been set,
a file-level dependency is created on that source file.
4. If the argument is a relative path and it exists in the current
source directory, a file-level dependency is created on that
file in the current source directory.
5. Otherwise, a file-level dependency is created on that path relative
to the current binary directory.
If any dependency is an ``OUTPUT`` of another custom command in the same
directory (``CMakeLists.txt`` file), CMake automatically brings the other
custom command into the target in which this command is built.
.. versionadded:: 3.16
A target-level dependency is added if any dependency is listed as
``BYPRODUCTS`` of a target or any of its build events in the same
directory to ensure the byproducts will be available.
If ``DEPENDS`` is not specified, the command will run whenever
the ``OUTPUT`` is missing; if the command does not actually
create the ``OUTPUT``, the rule will always run.
.. versionadded:: 3.1
Arguments to ``DEPENDS`` may use
:manual:`generator expressions <cmake-generator-expressions(7)>`.
``COMMAND_EXPAND_LISTS``
.. versionadded:: 3.8
Lists in ``COMMAND`` arguments will be expanded, including those
created with
:manual:`generator expressions <cmake-generator-expressions(7)>`,
allowing ``COMMAND`` arguments such as
``${CC} "-I$<JOIN:$<TARGET_PROPERTY:foo,INCLUDE_DIRECTORIES>,;-I>" foo.cc``
to be properly expanded.
``IMPLICIT_DEPENDS``
Request scanning of implicit dependencies of an input file.
The language given specifies the programming language whose
corresponding dependency scanner should be used.
Currently only ``C`` and ``CXX`` language scanners are supported.
The language has to be specified for every file in the
``IMPLICIT_DEPENDS`` list. Dependencies discovered from the
scanning are added to those of the custom command at build time.
Note that the ``IMPLICIT_DEPENDS`` option is currently supported
only for Makefile generators and will be ignored by other generators.
.. note::
This option cannot be specified at the same time as ``DEPFILE`` option.
``JOB_POOL``
.. versionadded:: 3.15
Specify a :prop_gbl:`pool <JOB_POOLS>` for the :generator:`Ninja`
generator. Incompatible with ``USES_TERMINAL``, which implies
the ``console`` pool.
Using a pool that is not defined by :prop_gbl:`JOB_POOLS` causes
an error by ninja at build time.
``JOB_SERVER_AWARE``
.. versionadded:: 3.28
Specify that the command is GNU Make job server aware.
For the :generator:`Unix Makefiles`, :generator:`MSYS Makefiles`, and
:generator:`MinGW Makefiles` generators this will add the ``+`` prefix to the
recipe line. See the `GNU Make Documentation`_ for more information.
This option is silently ignored by other generators.
.. _`GNU Make Documentation`: https://www.gnu.org/software/make/manual/html_node/MAKE-Variable.html
``MAIN_DEPENDENCY``
Specify the primary input source file to the command. This is
treated just like any value given to the ``DEPENDS`` option
but also suggests to Visual Studio generators where to hang
the custom command. Each source file may have at most one command
specifying it as its main dependency. A compile command (i.e. for a
library or an executable) counts as an implicit main dependency which
gets silently overwritten by a custom command specification.
``OUTPUT``
Specify the output files the command is expected to produce.
Each output file will be marked with the :prop_sf:`GENERATED`
source file property automatically.
If the output of the custom command is not actually created
as a file on disk it should be marked with the :prop_sf:`SYMBOLIC`
source file property.
If an output file name is a relative path, its absolute path is
determined by interpreting it relative to:
1. the build directory corresponding to the current source directory
(:variable:`CMAKE_CURRENT_BINARY_DIR`), or
2. the current source directory (:variable:`CMAKE_CURRENT_SOURCE_DIR`).
The path in the build directory is preferred unless the path in the
source tree is mentioned as an absolute source file path elsewhere
in the current directory.
The output file path may not contain ``<`` or ``>`` characters.
.. versionadded:: 3.20
Arguments to ``OUTPUT`` may use a restricted set of
:manual:`generator expressions <cmake-generator-expressions(7)>`.
:ref:`Target-dependent expressions <Target-Dependent Expressions>`
are not permitted.
.. versionchanged:: 3.28
In targets using :ref:`file sets`, custom command outputs are now
considered private unless they are listed in a non-private file set.
See policy :policy:`CMP0154`.
.. versionchanged:: 3.30
The output file path may now use ``#`` characters, except
when using the :generator:`Borland Makefiles` generator.
``USES_TERMINAL``
.. versionadded:: 3.2
The command will be given direct access to the terminal if possible.
With the :generator:`Ninja` generator, this places the command in
the ``console`` :prop_gbl:`pool <JOB_POOLS>`.
``VERBATIM``
All arguments to the commands will be escaped properly for the
build tool so that the invoked command receives each argument
unchanged. Note that one level of escapes is still used by the
CMake language processor before add_custom_command even sees the
arguments. Use of ``VERBATIM`` is recommended as it enables
correct behavior. When ``VERBATIM`` is not given the behavior
is platform specific because there is no protection of
tool-specific special characters.
``WORKING_DIRECTORY``
Execute the command with the given current working directory.
If it is a relative path it will be interpreted relative to the
build tree directory corresponding to the current source directory.
.. versionadded:: 3.13
Arguments to ``WORKING_DIRECTORY`` may use
:manual:`generator expressions <cmake-generator-expressions(7)>`.
``DEPFILE``
.. versionadded:: 3.7
Specify a depfile which holds dependencies for the custom command. It is
usually emitted by the custom command itself. This keyword may only be used
if the generator supports it, as detailed below.
The expected format, compatible with what is generated by ``gcc`` with the
option ``-M``, is independent of the generator or platform.
The formal syntax, as specified using
`BNF <https://en.wikipedia.org/wiki/Backus%E2%80%93Naur_form>`_ notation with
the regular extensions, is the following:
.. raw:: latex
\begin{small}
.. productionlist:: depfile
depfile: `rule`*
rule: `targets` (':' (`separator` `dependencies`?)?)? `eol`
targets: `target` (`separator` `target`)* `separator`*
target: `pathname`
dependencies: `dependency` (`separator` `dependency`)* `separator`*
dependency: `pathname`
separator: (`space` | `line_continue`)+
line_continue: '\' `eol`
space: ' ' | '\t'
pathname: `character`+
character: `std_character` | `dollar` | `hash` | `whitespace`
std_character: <any character except '$', '#' or ' '>
dollar: '$$'
hash: '\#'
whitespace: '\ '
eol: '\r'? '\n'
.. raw:: latex
\end{small}
.. note::
As part of ``pathname``, any slash and backslash is interpreted as
a directory separator.
.. versionadded:: 3.7
The :generator:`Ninja` generator supports ``DEPFILE`` since the keyword
was first added.
.. versionadded:: 3.17
Added the :generator:`Ninja Multi-Config` generator, which included
support for the ``DEPFILE`` keyword.
.. versionadded:: 3.20
Added support for :ref:`Makefile Generators`.
.. note::
``DEPFILE`` cannot be specified at the same time as the
``IMPLICIT_DEPENDS`` option for :ref:`Makefile Generators`.
.. versionadded:: 3.21
Added support for :ref:`Visual Studio Generators` with VS 2012 and above,
and for the :generator:`Xcode` generator. Support for
:manual:`generator expressions <cmake-generator-expressions(7)>` was also
added.
.. versionadded:: 3.29
The :ref:`Ninja Generators` will now incorporate the dependencies into its
"deps log" database if the file is not listed in ``OUTPUTS`` or
``BYPRODUCTS``.
Using ``DEPFILE`` with generators other than those listed above is an error.
If the ``DEPFILE`` argument is relative, it should be relative to
:variable:`CMAKE_CURRENT_BINARY_DIR`, and any relative paths inside the
``DEPFILE`` should also be relative to :variable:`CMAKE_CURRENT_BINARY_DIR`.
See policy :policy:`CMP0116`, which is always ``NEW`` for
:ref:`Makefile Generators`, :ref:`Visual Studio Generators`,
and the :generator:`Xcode` generator.
``DEPENDS_EXPLICIT_ONLY``
.. versionadded:: 3.27
Indicates that the command's ``DEPENDS`` argument represents all files
required by the command and implicit dependencies are not required.
Without this option, if any target uses the output of the custom command,
CMake will consider that target's dependencies as implicit dependencies for
the custom command in case this custom command requires files implicitly
created by those targets.
This option can be enabled on all custom commands by setting
:variable:`CMAKE_ADD_CUSTOM_COMMAND_DEPENDS_EXPLICIT_ONLY` to ``ON``.
Only the :ref:`Ninja Generators` actually use this information to remove
unnecessary implicit dependencies.
See also the :prop_tgt:`OPTIMIZE_DEPENDENCIES` target property, which may
provide another way for reducing the impact of target dependencies in some
scenarios.
Examples: Generating Files
^^^^^^^^^^^^^^^^^^^^^^^^^^
Custom commands may be used to generate source files.
For example, the code:
.. code-block:: cmake
add_custom_command(
OUTPUT out.c
COMMAND someTool -i ${CMAKE_CURRENT_SOURCE_DIR}/in.txt
-o out.c
DEPENDS ${CMAKE_CURRENT_SOURCE_DIR}/in.txt
VERBATIM)
add_library(myLib out.c)
adds a custom command to run ``someTool`` to generate ``out.c`` and then
compile the generated source as part of a library. The generation rule
will re-run whenever ``in.txt`` changes.
.. versionadded:: 3.20
One may use generator expressions to specify per-configuration outputs.
For example, the code:
.. code-block:: cmake
add_custom_command(
OUTPUT "out-$<CONFIG>.c"
COMMAND someTool -i ${CMAKE_CURRENT_SOURCE_DIR}/in.txt
-o "out-$<CONFIG>.c"
-c "$<CONFIG>"
DEPENDS ${CMAKE_CURRENT_SOURCE_DIR}/in.txt
VERBATIM)
add_library(myLib "out-$<CONFIG>.c")
adds a custom command to run ``someTool`` to generate ``out-<config>.c``,
where ``<config>`` is the build configuration, and then compile the generated
source as part of a library.
Example: Generating Files for Multiple Targets
""""""""""""""""""""""""""""""""""""""""""""""
If multiple independent targets need the same custom command output,
it must be attached to a single custom target on which they all depend.
Consider the following example:
.. code-block:: cmake
add_custom_command(
OUTPUT table.csv
COMMAND makeTable -i ${CMAKE_CURRENT_SOURCE_DIR}/input.dat
-o table.csv
DEPENDS ${CMAKE_CURRENT_SOURCE_DIR}/input.dat
VERBATIM)
add_custom_target(generate_table_csv DEPENDS table.csv)
add_custom_command(
OUTPUT foo.cxx
COMMAND genFromTable -i table.csv -case foo -o foo.cxx
DEPENDS table.csv # file-level dependency
generate_table_csv # target-level dependency
VERBATIM)
add_library(foo foo.cxx)
add_custom_command(
OUTPUT bar.cxx
COMMAND genFromTable -i table.csv -case bar -o bar.cxx
DEPENDS table.csv # file-level dependency
generate_table_csv # target-level dependency
VERBATIM)
add_library(bar bar.cxx)
Output ``foo.cxx`` is needed only by target ``foo`` and output ``bar.cxx``
is needed only by target ``bar``, but *both* targets need ``table.csv``,
transitively. Since ``foo`` and ``bar`` are independent targets that may
build concurrently, we prevent them from racing to generate ``table.csv``
by placing its custom command in a separate target, ``generate_table_csv``.
The custom commands generating ``foo.cxx`` and ``bar.cxx`` each specify a
target-level dependency on ``generate_table_csv``, so the targets using them,
``foo`` and ``bar``, will not build until after target ``generate_table_csv``
is built.
.. _`add_custom_command(TARGET)`:
Build Events
^^^^^^^^^^^^
The second signature adds a custom command to a target such as a
library or executable. This is useful for performing an operation
before or after building the target. The command becomes part of the
target and will only execute when the target itself is built. If the
target is already built, the command will not execute.
.. code-block:: cmake
add_custom_command(TARGET <target>
PRE_BUILD | PRE_LINK | POST_BUILD
COMMAND command1 [ARGS] [args1...]
[COMMAND command2 [ARGS] [args2...] ...]
[BYPRODUCTS [files...]]
[WORKING_DIRECTORY dir]
[COMMENT comment]
[VERBATIM]
[COMMAND_EXPAND_LISTS])
This defines a new command that will be associated with building the
specified ``<target>``. The ``<target>`` must be defined in the current
directory; targets defined in other directories may not be specified.
When the command will happen is determined by which
of the following is specified:
``PRE_BUILD``
This option has unique behavior for the :ref:`Visual Studio Generators`.
When using one of the Visual Studio generators, the command will run before
any other rules are executed within the target. With all other generators,
this option behaves the same as ``PRE_LINK`` instead. Because of this,
it is recommended to avoid using ``PRE_BUILD`` except when it is known that
a Visual Studio generator is being used.
``PRE_LINK``
Run after sources have been compiled but before linking the binary
or running the librarian or archiver tool of a static library.
This is not defined for targets created by the
:command:`add_custom_target` command.
``POST_BUILD``
Run after all other rules within the target have been executed.
Projects should always specify one of the above three keywords when using
the ``TARGET`` form. For backward compatibility reasons, ``POST_BUILD`` is
assumed if no such keyword is given, but projects should explicitly provide
one of the keywords to make clear the behavior they expect.
.. note::
Because generator expressions can be used in custom commands,
it is possible to define ``COMMAND`` lines or whole custom commands
which evaluate to empty strings for certain configurations.
For **Visual Studio 12 2013 (and newer)** generators these command
lines or custom commands will be omitted for the specific
configuration and no "empty-string-command" will be added.
This allows adding individual build events for every configuration.
.. versionadded:: 3.21
Support for target-dependent generator expressions.
.. versionadded:: 3.29
The ``<target>`` may be an :ref:`ALIAS target <Alias Targets>`.
Examples: Build Events
^^^^^^^^^^^^^^^^^^^^^^
A ``POST_BUILD`` event may be used to post-process a binary after linking.
For example, the code:
.. code-block:: cmake
add_executable(myExe myExe.c)
add_custom_command(
TARGET myExe POST_BUILD
COMMAND someHasher -i "$<TARGET_FILE:myExe>"
-o "$<TARGET_FILE:myExe>.hash"
VERBATIM)
will run ``someHasher`` to produce a ``.hash`` file next to the executable
after linking.
.. versionadded:: 3.20
One may use generator expressions to specify per-configuration byproducts.
For example, the code:
.. code-block:: cmake
add_library(myPlugin MODULE myPlugin.c)
add_custom_command(
TARGET myPlugin POST_BUILD
COMMAND someHasher -i "$<TARGET_FILE:myPlugin>"
--as-code "myPlugin-hash-$<CONFIG>.c"
BYPRODUCTS "myPlugin-hash-$<CONFIG>.c"
VERBATIM)
add_executable(myExe myExe.c "myPlugin-hash-$<CONFIG>.c")
will run ``someHasher`` after linking ``myPlugin``, e.g. to produce a ``.c``
file containing code to check the hash of ``myPlugin`` that the ``myExe``
executable can use to verify it before loading.
Ninja Multi-Config
^^^^^^^^^^^^^^^^^^
.. versionadded:: 3.20
``add_custom_command`` supports the :generator:`Ninja Multi-Config`
generator's cross-config capabilities. See the generator documentation
for more information.
See Also
^^^^^^^^
* :command:`add_custom_target`

211
cmake/share/cmake-3.30/Help/command/add_custom_target.rst Normal file
View File

@ -0,0 +1,211 @@
add_custom_target
-----------------
Add a target with no output so it will always be built.
.. code-block:: cmake
add_custom_target(Name [ALL] [command1 [args1...]]
[COMMAND command2 [args2...] ...]
[DEPENDS depend depend depend ... ]
[BYPRODUCTS [files...]]
[WORKING_DIRECTORY dir]
[COMMENT comment]
[JOB_POOL job_pool]
[JOB_SERVER_AWARE <bool>]
[VERBATIM] [USES_TERMINAL]
[COMMAND_EXPAND_LISTS]
[SOURCES src1 [src2...]])
Adds a target with the given name that executes the given commands.
The target has no output file and is *always considered out of date*
even if the commands try to create a file with the name of the target.
Use the :command:`add_custom_command` command to generate a file with
dependencies. By default nothing depends on the custom target. Use
the :command:`add_dependencies` command to add dependencies to or
from other targets.
The options are:
``ALL``
Indicate that this target should be added to the default build
target so that it will be run every time (the command cannot be
called ``ALL``).
``BYPRODUCTS``
.. versionadded:: 3.2
Specify the files the command is expected to produce but whose
modification time may or may not be updated on subsequent builds.
If a byproduct name is a relative path it will be interpreted
relative to the build tree directory corresponding to the
current source directory.
Each byproduct file will be marked with the :prop_sf:`GENERATED`
source file property automatically.
*See policy* :policy:`CMP0058` *for the motivation behind this feature.*
Explicit specification of byproducts is supported by the
:generator:`Ninja` generator to tell the ``ninja`` build tool
how to regenerate byproducts when they are missing. It is
also useful when other build rules (e.g. custom commands)
depend on the byproducts. Ninja requires a build rule for any
generated file on which another rule depends even if there are
order-only dependencies to ensure the byproducts will be
available before their dependents build.
The :ref:`Makefile Generators` will remove ``BYPRODUCTS`` and other
:prop_sf:`GENERATED` files during ``make clean``.
.. versionadded:: 3.20
Arguments to ``BYPRODUCTS`` may use a restricted set of
:manual:`generator expressions <cmake-generator-expressions(7)>`.
:ref:`Target-dependent expressions <Target-Dependent Expressions>`
are not permitted.
.. versionchanged:: 3.28
In custom targets using :ref:`file sets`, byproducts are now
considered private unless they are listed in a non-private file set.
See policy :policy:`CMP0154`.
``COMMAND``
Specify the command-line(s) to execute at build time.
If more than one ``COMMAND`` is specified they will be executed in order,
but *not* necessarily composed into a stateful shell or batch script.
(To run a full script, use the :command:`configure_file` command or the
:command:`file(GENERATE)` command to create it, and then specify
a ``COMMAND`` to launch it.)
If ``COMMAND`` specifies an executable target name (created by the
:command:`add_executable` command), it will automatically be replaced
by the location of the executable created at build time if either of
the following is true:
* The target is not being cross-compiled (i.e. the
:variable:`CMAKE_CROSSCOMPILING` variable is not set to true).
* .. versionadded:: 3.6
The target is being cross-compiled and an emulator is provided (i.e.
its :prop_tgt:`CROSSCOMPILING_EMULATOR` target property is set).
In this case, the contents of :prop_tgt:`CROSSCOMPILING_EMULATOR` will be
prepended to the command before the location of the target executable.
If neither of the above conditions are met, it is assumed that the
command name is a program to be found on the ``PATH`` at build time.
Arguments to ``COMMAND`` may use
:manual:`generator expressions <cmake-generator-expressions(7)>`.
Use the :genex:`TARGET_FILE` generator expression to refer to the location
of a target later in the command line (i.e. as a command argument rather
than as the command to execute).
Whenever one of the following target based generator expressions are used as
a command to execute or is mentioned in a command argument, a target-level
dependency will be added automatically so that the mentioned target will be
built before this custom target (see policy :policy:`CMP0112`).
* ``TARGET_FILE``
* ``TARGET_LINKER_FILE``
* ``TARGET_SONAME_FILE``
* ``TARGET_PDB_FILE``
The command and arguments are optional and if not specified an empty
target will be created.
``COMMENT``
Display the given message before the commands are executed at
build time.
.. versionadded:: 3.26
Arguments to ``COMMENT`` may use
:manual:`generator expressions <cmake-generator-expressions(7)>`.
``DEPENDS``
Reference files and outputs of custom commands created with
:command:`add_custom_command` command calls in the same directory
(``CMakeLists.txt`` file). They will be brought up to date when
the target is built.
.. versionchanged:: 3.16
A target-level dependency is added if any dependency is a byproduct
of a target or any of its build events in the same directory to ensure
the byproducts will be available before this target is built.
Use the :command:`add_dependencies` command to add dependencies
on other targets.
``COMMAND_EXPAND_LISTS``
.. versionadded:: 3.8
Lists in ``COMMAND`` arguments will be expanded, including those
created with
:manual:`generator expressions <cmake-generator-expressions(7)>`,
allowing ``COMMAND`` arguments such as
``${CC} "-I$<JOIN:$<TARGET_PROPERTY:foo,INCLUDE_DIRECTORIES>,;-I>" foo.cc``
to be properly expanded.
``JOB_POOL``
.. versionadded:: 3.15
Specify a :prop_gbl:`pool <JOB_POOLS>` for the :generator:`Ninja`
generator. Incompatible with ``USES_TERMINAL``, which implies
the ``console`` pool.
Using a pool that is not defined by :prop_gbl:`JOB_POOLS` causes
an error by ninja at build time.
``JOB_SERVER_AWARE``
.. versionadded:: 3.28
Specify that the command is GNU Make job server aware.
For the :generator:`Unix Makefiles`, :generator:`MSYS Makefiles`, and
:generator:`MinGW Makefiles` generators this will add the ``+`` prefix to the
recipe line. See the `GNU Make Documentation`_ for more information.
This option is silently ignored by other generators.
.. _`GNU Make Documentation`: https://www.gnu.org/software/make/manual/html_node/MAKE-Variable.html
``SOURCES``
Specify additional source files to be included in the custom target.
Specified source files will be added to IDE project files for
convenience in editing even if they have no build rules.
``VERBATIM``
All arguments to the commands will be escaped properly for the
build tool so that the invoked command receives each argument
unchanged. Note that one level of escapes is still used by the
CMake language processor before ``add_custom_target`` even sees
the arguments. Use of ``VERBATIM`` is recommended as it enables
correct behavior. When ``VERBATIM`` is not given the behavior
is platform specific because there is no protection of
tool-specific special characters.
``USES_TERMINAL``
.. versionadded:: 3.2
The command will be given direct access to the terminal if possible.
With the :generator:`Ninja` generator, this places the command in
the ``console`` :prop_gbl:`pool <JOB_POOLS>`.
``WORKING_DIRECTORY``
Execute the command with the given current working directory.
If it is a relative path it will be interpreted relative to the
build tree directory corresponding to the current source directory.
.. versionadded:: 3.13
Arguments to ``WORKING_DIRECTORY`` may use
:manual:`generator expressions <cmake-generator-expressions(7)>`.
Ninja Multi-Config
^^^^^^^^^^^^^^^^^^
.. versionadded:: 3.20
``add_custom_target`` supports the :generator:`Ninja Multi-Config`
generator's cross-config capabilities. See the generator documentation
for more information.
See Also
^^^^^^^^
* :command:`add_custom_command`

38
cmake/share/cmake-3.30/Help/command/add_definitions.rst Normal file
View File

@ -0,0 +1,38 @@
add_definitions
---------------
Add ``-D`` define flags to the compilation of source files.
.. code-block:: cmake
add_definitions(-DFOO -DBAR ...)
Adds definitions to the compiler command line for targets in the current
directory, whether added before or after this command is invoked, and for
the ones in sub-directories added after. This command can be used to add any
flags, but it is intended to add preprocessor definitions.
.. note::
This command has been superseded by alternatives:
* Use :command:`add_compile_definitions` to add preprocessor definitions.
* Use :command:`include_directories` to add include directories.
* Use :command:`add_compile_options` to add other options.
Flags beginning in ``-D`` or ``/D`` that look like preprocessor definitions are
automatically added to the :prop_dir:`COMPILE_DEFINITIONS` directory
property for the current directory. Definitions with non-trivial values
may be left in the set of flags instead of being converted for reasons of
backwards compatibility. See documentation of the
:prop_dir:`directory <COMPILE_DEFINITIONS>`,
:prop_tgt:`target <COMPILE_DEFINITIONS>`,
:prop_sf:`source file <COMPILE_DEFINITIONS>` ``COMPILE_DEFINITIONS``
properties for details on adding preprocessor definitions to specific
scopes and configurations.
See Also
^^^^^^^^
* The :manual:`cmake-buildsystem(7)` manual for more on defining
buildsystem properties.

42
cmake/share/cmake-3.30/Help/command/add_dependencies.rst Normal file
View File

@ -0,0 +1,42 @@
add_dependencies
----------------
Add a dependency between top-level targets.
.. code-block:: cmake
add_dependencies(<target> [<target-dependency>]...)
Makes a top-level ``<target>`` depend on other top-level targets to
ensure that they build before ``<target>`` does. A top-level target
is one created by one of the :command:`add_executable`,
:command:`add_library`, or :command:`add_custom_target` commands
(but not targets generated by CMake like ``install``).
Dependencies added to an :ref:`imported target <Imported Targets>`
or an :ref:`interface library <Interface Libraries>` are followed
transitively in its place since the target itself does not build.
.. versionadded:: 3.3
Allow adding dependencies to interface libraries.
.. versionadded:: 3.8
Dependencies will populate the :prop_tgt:`MANUALLY_ADDED_DEPENDENCIES`
property of ``<target>``.
.. versionchanged:: 3.9
The :ref:`Ninja Generators` use weaker ordering than
other generators in order to improve available concurrency.
They only guarantee that the dependencies' custom commands are
finished before sources in ``<target>`` start compiling; this
ensures generated sources are available.
See Also
^^^^^^^^
* The ``DEPENDS`` option of :command:`add_custom_target` and
:command:`add_custom_command` commands for adding file-level
dependencies in custom rules.
* The :prop_sf:`OBJECT_DEPENDS` source file property to add
file-level dependencies to object files.

123
cmake/share/cmake-3.30/Help/command/add_executable.rst Normal file
View File

@ -0,0 +1,123 @@
add_executable
--------------
.. only:: html
.. contents::
Add an executable to the project using the specified source files.
Normal Executables
^^^^^^^^^^^^^^^^^^
.. signature::
add_executable(<name> <options>... <sources>...)
:target: normal
Add an executable target called ``<name>`` to be built from the source
files listed in the command invocation.
The options are:
``WIN32``
Set the :prop_tgt:`WIN32_EXECUTABLE` target property automatically.
See documentation of that target property for details.
``MACOSX_BUNDLE``
Set the :prop_tgt:`MACOSX_BUNDLE` target property automatically.
See documentation of that target property for details.
``EXCLUDE_FROM_ALL``
Set the :prop_tgt:`EXCLUDE_FROM_ALL` target property automatically.
See documentation of that target property for details.
The ``<name>`` corresponds to the logical target name and must be globally
unique within a project. The actual file name of the executable built is
constructed based on conventions of the native platform (such as
``<name>.exe`` or just ``<name>``).
.. versionadded:: 3.1
Source arguments to ``add_executable`` may use "generator expressions" with
the syntax ``$<...>``. See the :manual:`cmake-generator-expressions(7)`
manual for available expressions.
.. versionadded:: 3.11
The source files can be omitted if they are added later using
:command:`target_sources`.
By default the executable file will be created in the build tree
directory corresponding to the source tree directory in which the
command was invoked. See documentation of the
:prop_tgt:`RUNTIME_OUTPUT_DIRECTORY` target property to change this
location. See documentation of the :prop_tgt:`OUTPUT_NAME` target property
to change the ``<name>`` part of the final file name.
See the :manual:`cmake-buildsystem(7)` manual for more on defining
buildsystem properties.
See also :prop_sf:`HEADER_FILE_ONLY` on what to do if some sources are
pre-processed, and you want to have the original sources reachable from
within IDE.
Imported Executables
^^^^^^^^^^^^^^^^^^^^
.. signature::
add_executable(<name> IMPORTED [GLOBAL])
:target: IMPORTED
Add an :ref:`IMPORTED executable target <Imported Targets>` to reference
an executable file located outside the project. The target name may be
referenced like any target built within the project, except that by
default it is visible only in the directory in which it is created,
and below.
The options are:
``GLOBAL``
Make the target name globally visible.
No rules are generated to build imported targets, and the :prop_tgt:`IMPORTED`
target property is ``True``. Imported executables are useful for convenient
reference from commands like :command:`add_custom_command`.
Details about the imported executable are specified by setting properties
whose names begin in ``IMPORTED_``. The most important such property is
:prop_tgt:`IMPORTED_LOCATION` (and its per-configuration version
:prop_tgt:`IMPORTED_LOCATION_<CONFIG>`) which specifies the location of
the main executable file on disk. See documentation of the ``IMPORTED_*``
properties for more information.
Alias Executables
^^^^^^^^^^^^^^^^^
.. signature::
add_executable(<name> ALIAS <target>)
:target: ALIAS
Creates an :ref:`Alias Target <Alias Targets>`, such that ``<name>`` can
be used to refer to ``<target>`` in subsequent commands. The ``<name>``
does not appear in the generated buildsystem as a make target. The
``<target>`` may not be an ``ALIAS``.
.. versionadded:: 3.11
An ``ALIAS`` can target a ``GLOBAL`` :ref:`Imported Target <Imported Targets>`
.. versionadded:: 3.18
An ``ALIAS`` can target a non-``GLOBAL`` Imported Target. Such alias is
scoped to the directory in which it is created and subdirectories.
The :prop_tgt:`ALIAS_GLOBAL` target property can be used to check if the
alias is global or not.
``ALIAS`` targets can be used as targets to read properties
from, executables for custom commands and custom targets. They can also be
tested for existence with the regular :command:`if(TARGET)` subcommand.
The ``<name>`` may not be used to modify properties of ``<target>``, that
is, it may not be used as the operand of :command:`set_property`,
:command:`set_target_properties`, :command:`target_link_libraries` etc.
An ``ALIAS`` target may not be installed or exported.
See Also
^^^^^^^^
* :command:`add_library`

302
cmake/share/cmake-3.30/Help/command/add_library.rst Normal file
View File

@ -0,0 +1,302 @@
add_library
-----------
.. only:: html
.. contents::
Add a library to the project using the specified source files.
Normal Libraries
^^^^^^^^^^^^^^^^
.. signature::
add_library(<name> [<type>] [EXCLUDE_FROM_ALL] <sources>...)
:target: normal
Add a library target called ``<name>`` to be built from the source files
listed in the command invocation.
The optional ``<type>`` specifies the type of library to be created:
``STATIC``
An archive of object files for use when linking other targets.
``SHARED``
A dynamic library that may be linked by other targets and loaded
at runtime.
``MODULE``
A plugin that may not be linked by other targets, but may be
dynamically loaded at runtime using dlopen-like functionality.
If no ``<type>`` is given the default is ``STATIC`` or ``SHARED``
based on the value of the :variable:`BUILD_SHARED_LIBS` variable.
The options are:
``EXCLUDE_FROM_ALL``
Set the :prop_tgt:`EXCLUDE_FROM_ALL` target property automatically.
See documentation of that target property for details.
The ``<name>`` corresponds to the logical target name and must be globally
unique within a project. The actual file name of the library built is
constructed based on conventions of the native platform (such as
``lib<name>.a`` or ``<name>.lib``).
.. versionadded:: 3.1
Source arguments to ``add_library`` may use "generator expressions" with
the syntax ``$<...>``. See the :manual:`cmake-generator-expressions(7)`
manual for available expressions.
.. versionadded:: 3.11
The source files can be omitted if they are added later using
:command:`target_sources`.
For ``SHARED`` and ``MODULE`` libraries the
:prop_tgt:`POSITION_INDEPENDENT_CODE` target
property is set to ``ON`` automatically.
A ``SHARED`` library may be marked with the :prop_tgt:`FRAMEWORK`
target property to create an macOS Framework.
.. versionadded:: 3.8
A ``STATIC`` library may be marked with the :prop_tgt:`FRAMEWORK`
target property to create a static Framework.
If a library does not export any symbols, it must not be declared as a
``SHARED`` library. For example, a Windows resource DLL or a managed C++/CLI
DLL that exports no unmanaged symbols would need to be a ``MODULE`` library.
This is because CMake expects a ``SHARED`` library to always have an
associated import library on Windows.
By default the library file will be created in the build tree directory
corresponding to the source tree directory in which the command was
invoked. See documentation of the :prop_tgt:`ARCHIVE_OUTPUT_DIRECTORY`,
:prop_tgt:`LIBRARY_OUTPUT_DIRECTORY`, and
:prop_tgt:`RUNTIME_OUTPUT_DIRECTORY` target properties to change this
location. See documentation of the :prop_tgt:`OUTPUT_NAME` target
property to change the ``<name>`` part of the final file name.
See the :manual:`cmake-buildsystem(7)` manual for more on defining
buildsystem properties.
See also :prop_sf:`HEADER_FILE_ONLY` on what to do if some sources are
pre-processed, and you want to have the original sources reachable from
within IDE.
.. versionchanged:: 3.30
On platforms that do not support shared libraries, ``add_library``
now fails on calls creating ``SHARED`` libraries instead of
automatically converting them to ``STATIC`` libraries as before.
See policy :policy:`CMP0164`.
Object Libraries
^^^^^^^^^^^^^^^^
.. signature::
add_library(<name> OBJECT <sources>...)
:target: OBJECT
Add an :ref:`Object Library <Object Libraries>` to compile source files
without archiving or linking their object files into a library.
Other targets created by ``add_library`` or :command:`add_executable`
may reference the objects using an expression of the
form :genex:`$\<TARGET_OBJECTS:objlib\> <TARGET_OBJECTS>` as a source, where
``objlib`` is the object library name. For example:
.. code-block:: cmake
add_library(... $<TARGET_OBJECTS:objlib> ...)
add_executable(... $<TARGET_OBJECTS:objlib> ...)
will include objlib's object files in a library and an executable
along with those compiled from their own sources. Object libraries
may contain only sources that compile, header files, and other files
that would not affect linking of a normal library (e.g. ``.txt``).
They may contain custom commands generating such sources, but not
``PRE_BUILD``, ``PRE_LINK``, or ``POST_BUILD`` commands. Some native build
systems (such as Xcode) may not like targets that have only object files, so
consider adding at least one real source file to any target that references
:genex:`$\<TARGET_OBJECTS:objlib\> <TARGET_OBJECTS>`.
.. versionadded:: 3.12
Object libraries can be linked to with :command:`target_link_libraries`.
Interface Libraries
^^^^^^^^^^^^^^^^^^^
.. signature::
add_library(<name> INTERFACE)
:target: INTERFACE
Add an :ref:`Interface Library <Interface Libraries>` target that may
specify usage requirements for dependents but does not compile sources
and does not produce a library artifact on disk.
An interface library with no source files is not included as a target
in the generated buildsystem. However, it may have
properties set on it and it may be installed and exported.
Typically, ``INTERFACE_*`` properties are populated on an interface
target using the commands:
* :command:`set_property`,
* :command:`target_link_libraries(INTERFACE)`,
* :command:`target_link_options(INTERFACE)`,
* :command:`target_include_directories(INTERFACE)`,
* :command:`target_compile_options(INTERFACE)`,
* :command:`target_compile_definitions(INTERFACE)`, and
* :command:`target_sources(INTERFACE)`,
and then it is used as an argument to :command:`target_link_libraries`
like any other target.
.. versionadded:: 3.15
An interface library can have :prop_tgt:`PUBLIC_HEADER` and
:prop_tgt:`PRIVATE_HEADER` properties. The headers specified by those
properties can be installed using the :command:`install(TARGETS)` command.
.. signature::
add_library(<name> INTERFACE [EXCLUDE_FROM_ALL] <sources>...)
:target: INTERFACE-with-sources
.. versionadded:: 3.19
Add an :ref:`Interface Library <Interface Libraries>` target with
source files (in addition to usage requirements and properties as
documented by the :command:`above signature <add_library(INTERFACE)>`).
Source files may be listed directly in the ``add_library`` call
or added later by calls to :command:`target_sources` with the
``PRIVATE`` or ``PUBLIC`` keywords.
If an interface library has source files (i.e. the :prop_tgt:`SOURCES`
target property is set), or header sets (i.e. the :prop_tgt:`HEADER_SETS`
target property is set), it will appear in the generated buildsystem
as a build target much like a target defined by the
:command:`add_custom_target` command. It does not compile any sources,
but does contain build rules for custom commands created by the
:command:`add_custom_command` command.
The options are:
``EXCLUDE_FROM_ALL``
Set the :prop_tgt:`EXCLUDE_FROM_ALL` target property automatically.
See documentation of that target property for details.
.. note::
In most command signatures where the ``INTERFACE`` keyword appears,
the items listed after it only become part of that target's usage
requirements and are not part of the target's own settings. However,
in this signature of ``add_library``, the ``INTERFACE`` keyword refers
to the library type only. Sources listed after it in the ``add_library``
call are ``PRIVATE`` to the interface library and do not appear in its
:prop_tgt:`INTERFACE_SOURCES` target property.
.. _`add_library imported libraries`:
Imported Libraries
^^^^^^^^^^^^^^^^^^
.. signature::
add_library(<name> <type> IMPORTED [GLOBAL])
:target: IMPORTED
Add an :ref:`IMPORTED library target <Imported Targets>` called ``<name>``.
The target name may be referenced like any target built within the project,
except that by default it is visible only in the directory in which it is
created, and below.
The ``<type>`` must be one of:
``STATIC``, ``SHARED``, ``MODULE``, ``UNKNOWN``
References a library file located outside the project. The
:prop_tgt:`IMPORTED_LOCATION` target property (or its per-configuration
variant :prop_tgt:`IMPORTED_LOCATION_<CONFIG>`) specifies the
location of the main library file on disk:
* For a ``SHARED`` library on most non-Windows platforms, the main library
file is the ``.so`` or ``.dylib`` file used by both linkers and dynamic
loaders. If the referenced library file has a ``SONAME`` (or on macOS,
has a ``LC_ID_DYLIB`` starting in ``@rpath/``), the value of that field
should be set in the :prop_tgt:`IMPORTED_SONAME` target property.
If the referenced library file does not have a ``SONAME``, but the
platform supports it, then the :prop_tgt:`IMPORTED_NO_SONAME` target
property should be set.
* For a ``SHARED`` library on Windows, the :prop_tgt:`IMPORTED_IMPLIB`
target property (or its per-configuration variant
:prop_tgt:`IMPORTED_IMPLIB_<CONFIG>`) specifies the location of the
DLL import library file (``.lib`` or ``.dll.a``) on disk, and the
``IMPORTED_LOCATION`` is the location of the ``.dll`` runtime
library (and is optional, but needed by the :genex:`TARGET_RUNTIME_DLLS`
generator expression).
Additional usage requirements may be specified in ``INTERFACE_*``
properties.
An ``UNKNOWN`` library type is typically only used in the implementation
of :ref:`Find Modules`. It allows the path to an imported library
(often found using the :command:`find_library` command) to be used
without having to know what type of library it is. This is especially
useful on Windows where a static library and a DLL's import library
both have the same file extension.
``OBJECT``
References a set of object files located outside the project.
The :prop_tgt:`IMPORTED_OBJECTS` target property (or its per-configuration
variant :prop_tgt:`IMPORTED_OBJECTS_<CONFIG>`) specifies the locations of
object files on disk.
Additional usage requirements may be specified in ``INTERFACE_*``
properties.
``INTERFACE``
Does not reference any library or object files on disk, but may
specify usage requirements in ``INTERFACE_*`` properties.
The options are:
``GLOBAL``
Make the target name globally visible.
No rules are generated to build imported targets, and the :prop_tgt:`IMPORTED`
target property is ``True``. Imported libraries are useful for convenient
reference from commands like :command:`target_link_libraries`.
Details about the imported library are specified by setting properties whose
names begin in ``IMPORTED_`` and ``INTERFACE_``. See documentation of
such properties for more information.
Alias Libraries
^^^^^^^^^^^^^^^
.. signature::
add_library(<name> ALIAS <target>)
:target: ALIAS
Creates an :ref:`Alias Target <Alias Targets>`, such that ``<name>`` can be
used to refer to ``<target>`` in subsequent commands. The ``<name>`` does
not appear in the generated buildsystem as a make target. The ``<target>``
may not be an ``ALIAS``.
.. versionadded:: 3.11
An ``ALIAS`` can target a ``GLOBAL`` :ref:`Imported Target <Imported Targets>`
.. versionadded:: 3.18
An ``ALIAS`` can target a non-``GLOBAL`` Imported Target. Such alias is
scoped to the directory in which it is created and below.
The :prop_tgt:`ALIAS_GLOBAL` target property can be used to check if the
alias is global or not.
``ALIAS`` targets can be used as linkable targets and as targets to
read properties from. They can also be tested for existence with the
regular :command:`if(TARGET)` subcommand. The ``<name>`` may not be used
to modify properties of ``<target>``, that is, it may not be used as the
operand of :command:`set_property`, :command:`set_target_properties`,
:command:`target_link_libraries` etc. An ``ALIAS`` target may not be
installed or exported.
See Also
^^^^^^^^
* :command:`add_executable`

44
cmake/share/cmake-3.30/Help/command/add_link_options.rst Normal file
View File

@ -0,0 +1,44 @@
add_link_options
----------------
.. versionadded:: 3.13
Add options to the link step for executable, shared library or module
library targets in the current directory and below that are added after
this command is invoked.
.. code-block:: cmake
add_link_options(<option> ...)
This command can be used to add any link options, but alternative commands
exist to add libraries (:command:`target_link_libraries` or
:command:`link_libraries`). See documentation of the
:prop_dir:`directory <LINK_OPTIONS>` and
:prop_tgt:`target <LINK_OPTIONS>` ``LINK_OPTIONS`` properties.
.. note::
This command cannot be used to add options for static library targets,
since they do not use a linker. To add archiver or MSVC librarian flags,
see the :prop_tgt:`STATIC_LIBRARY_OPTIONS` target property.
.. |command_name| replace:: ``add_link_options``
.. include:: GENEX_NOTE.txt
.. include:: DEVICE_LINK_OPTIONS.txt
.. include:: OPTIONS_SHELL.txt
.. include:: LINK_OPTIONS_LINKER.txt
See Also
^^^^^^^^
* :command:`link_libraries`
* :command:`target_link_libraries`
* :command:`target_link_options`
* :variable:`CMAKE_<LANG>_FLAGS` and :variable:`CMAKE_<LANG>_FLAGS_<CONFIG>`
add language-wide flags passed to all invocations of the compiler.
This includes invocations that drive compiling and those that drive linking.

32
cmake/share/cmake-3.30/Help/command/add_subdirectory.rst Normal file
View File

@ -0,0 +1,32 @@
add_subdirectory
----------------
Add a subdirectory to the build.
.. code-block:: cmake
add_subdirectory(source_dir [binary_dir] [EXCLUDE_FROM_ALL] [SYSTEM])
Adds a subdirectory to the build. The ``source_dir`` specifies the
directory in which the source ``CMakeLists.txt`` and code files are
located. If it is a relative path, it will be evaluated with respect
to the current directory (the typical usage), but it may also be an
absolute path. The ``binary_dir`` specifies the directory in which to
place the output files. If it is a relative path, it will be evaluated
with respect to the current output directory, but it may also be an
absolute path. If ``binary_dir`` is not specified, the value of
``source_dir``, before expanding any relative path, will be used (the
typical usage). The ``CMakeLists.txt`` file in the specified source
directory will be processed immediately by CMake before processing in
the current input file continues beyond this command.
If the ``EXCLUDE_FROM_ALL`` argument is provided then the
:prop_dir:`EXCLUDE_FROM_ALL` property will be set on the added directory.
This will exclude the directory from a default build. See the directory
property :prop_dir:`EXCLUDE_FROM_ALL` for full details.
.. versionadded:: 3.25
If the ``SYSTEM`` argument is provided, the :prop_dir:`SYSTEM` directory
property of the subdirectory will be set to true. This property is
used to initialize the :prop_tgt:`SYSTEM` property of each non-imported
target created in that subdirectory.

117
cmake/share/cmake-3.30/Help/command/add_test.rst Normal file
View File

@ -0,0 +1,117 @@
add_test
--------
Add a test to the project to be run by :manual:`ctest(1)`.
.. code-block:: cmake
add_test(NAME <name> COMMAND <command> [<arg>...]
[CONFIGURATIONS <config>...]
[WORKING_DIRECTORY <dir>]
[COMMAND_EXPAND_LISTS])
Adds a test called ``<name>``. The test name may contain arbitrary
characters, expressed as a :ref:`Quoted Argument` or :ref:`Bracket Argument`
if necessary. See policy :policy:`CMP0110`.
CMake only generates tests if the :command:`enable_testing` command has been
invoked. The :module:`CTest` module invokes ``enable_testing`` automatically
unless ``BUILD_TESTING`` is set to ``OFF``.
Tests added with the ``add_test(NAME)`` signature support using
:manual:`generator expressions <cmake-generator-expressions(7)>`
in test properties set by :command:`set_property(TEST)` or
:command:`set_tests_properties`. Test properties may only be set in the
directory the test is created in.
``add_test`` options are:
``COMMAND``
Specify the test command-line.
If ``<command>`` specifies an executable target created by
:command:`add_executable`:
* It will automatically be replaced by the location of the executable
created at build time.
* .. versionadded:: 3.3
The target's :prop_tgt:`CROSSCOMPILING_EMULATOR`, if set, will be
used to run the command on the host::
<emulator> <command>
.. versionchanged:: 3.29
The emulator is used only when
:variable:`cross-compiling <CMAKE_CROSSCOMPILING>`.
See policy :policy:`CMP0158`.
* .. versionadded:: 3.29
The target's :prop_tgt:`TEST_LAUNCHER`, if set, will be
used to launch the command::
<launcher> <command>
If the :prop_tgt:`CROSSCOMPILING_EMULATOR` is also set, both are used::
<launcher> <emulator> <command>
The command may be specified using
:manual:`generator expressions <cmake-generator-expressions(7)>`.
``CONFIGURATIONS``
Restrict execution of the test only to the named configurations.
``WORKING_DIRECTORY``
Set the test property :prop_test:`WORKING_DIRECTORY` in which to execute the
test. If not specified, the test will be run in
:variable:`CMAKE_CURRENT_BINARY_DIR`. The working directory may be specified
using :manual:`generator expressions <cmake-generator-expressions(7)>`.
``COMMAND_EXPAND_LISTS``
.. versionadded:: 3.16
Lists in ``COMMAND`` arguments will be expanded, including those created with
:manual:`generator expressions <cmake-generator-expressions(7)>`.
If the test command exits with code ``0`` the test passes. Non-zero exit code
is a "failed" test. The test property :prop_test:`WILL_FAIL` inverts this
logic. Note that system-level test failures such as segmentation faults or
heap errors will still fail the test even if ``WILL_FAIL`` is true. Output
written to stdout or stderr is captured by :manual:`ctest(1)` and only
affects the pass/fail status via the :prop_test:`PASS_REGULAR_EXPRESSION`,
:prop_test:`FAIL_REGULAR_EXPRESSION`, or :prop_test:`SKIP_REGULAR_EXPRESSION`
test properties.
.. versionadded:: 3.16
Added :prop_test:`SKIP_REGULAR_EXPRESSION` property.
Example usage:
.. code-block:: cmake
add_test(NAME mytest
COMMAND testDriver --config $<CONFIG>
--exe $<TARGET_FILE:myexe>)
This creates a test ``mytest`` whose command runs a ``testDriver`` tool
passing the configuration name and the full path to the executable
file produced by target ``myexe``.
---------------------------------------------------------------------
The command syntax above is recommended over the older, less flexible form:
.. code-block:: cmake
add_test(<name> <command> [<arg>...])
Add a test called ``<name>`` with the given command-line.
Unlike the above ``NAME`` signature, target names are not supported
in the command-line. Furthermore, tests added with this signature do not
support :manual:`generator expressions <cmake-generator-expressions(7)>`
in the command-line or test properties.

24
cmake/share/cmake-3.30/Help/command/aux_source_directory.rst Normal file
View File

@ -0,0 +1,24 @@
aux_source_directory
--------------------
Find all source files in a directory.
.. code-block:: cmake
aux_source_directory(<dir> <variable>)
Collects the names of all the source files in the specified directory
and stores the list in the ``<variable>`` provided. This command is
intended to be used by projects that use explicit template
instantiation. Template instantiation files can be stored in a
``Templates`` subdirectory and collected automatically using this
command to avoid manually listing all instantiations.
It is tempting to use this command to avoid writing the list of source
files for a library or executable target. While this seems to work,
there is no way for CMake to generate a build system that knows when a
new source file has been added. Normally the generated build system
knows when it needs to rerun CMake because the ``CMakeLists.txt`` file is
modified to add a new source. When the source is just added to the
directory without modifying this file, one would have to manually
rerun CMake to generate a build system incorporating the new file.

77
cmake/share/cmake-3.30/Help/command/block.rst Normal file
View File

@ -0,0 +1,77 @@
block
-----
.. versionadded:: 3.25
Evaluate a group of commands with a dedicated variable and/or policy scope.
.. code-block:: cmake
block([SCOPE_FOR [POLICIES] [VARIABLES] ] [PROPAGATE <var-name>...])
<commands>
endblock()
All commands between ``block()`` and the matching :command:`endblock` are
recorded without being invoked. Once the :command:`endblock` is evaluated, the
recorded list of commands is invoked inside the requested scopes, then the
scopes created by the ``block()`` command are removed.
``SCOPE_FOR``
Specify which scopes must be created.
``POLICIES``
Create a new policy scope. This is equivalent to
:command:`cmake_policy(PUSH)` with an automatic
:command:`cmake_policy(POP)` when leaving the block scope.
``VARIABLES``
Create a new variable scope.
If ``SCOPE_FOR`` is not specified, this is equivalent to:
.. code-block:: cmake
block(SCOPE_FOR VARIABLES POLICIES)
``PROPAGATE``
When a variable scope is created by the :command:`block` command, this
option sets or unsets the specified variables in the parent scope. This is
equivalent to :command:`set(PARENT_SCOPE)` or :command:`unset(PARENT_SCOPE)`
commands.
.. code-block:: cmake
set(var1 "INIT1")
set(var2 "INIT2")
block(PROPAGATE var1 var2)
set(var1 "VALUE1")
unset(var2)
endblock()
# Now var1 holds VALUE1, and var2 is unset
This option is only allowed when a variable scope is created. An error will
be raised in the other cases.
When the ``block()`` is inside a :command:`foreach` or :command:`while`
command, the :command:`break` and :command:`continue` commands can be used
inside the block.
.. code-block:: cmake
while(TRUE)
block()
...
# the break() command will terminate the while() command
break()
endblock()
endwhile()
See Also
^^^^^^^^
* :command:`endblock`
* :command:`return`
* :command:`cmake_policy`

12
cmake/share/cmake-3.30/Help/command/break.rst Normal file
View File

@ -0,0 +1,12 @@
break
-----
Break from an enclosing foreach or while loop.
.. code-block:: cmake
break()
Breaks from an enclosing :command:`foreach` or :command:`while` loop.
See also the :command:`continue` command.

51
cmake/share/cmake-3.30/Help/command/build_command.rst Normal file
View File

@ -0,0 +1,51 @@
build_command
-------------
Get a command line to build the current project.
This is mainly intended for internal use by the :module:`CTest` module.
.. code-block:: cmake
build_command(<variable>
[CONFIGURATION <config>]
[PARALLEL_LEVEL <parallel>]
[TARGET <target>]
[PROJECT_NAME <projname>] # legacy, causes warning
)
Sets the given ``<variable>`` to a command-line string of the form::
<cmake> --build . [--config <config>] [--parallel <parallel>] [--target <target>...] [-- -i]
where ``<cmake>`` is the location of the :manual:`cmake(1)` command-line
tool, and ``<config>``, ``<parallel>`` and ``<target>`` are the values
provided to the ``CONFIGURATION``, ``PARALLEL_LEVEL`` and ``TARGET``
options, if any. The trailing ``-- -i`` option is added for
:ref:`Makefile Generators` if policy :policy:`CMP0061` is not set to
``NEW``.
When invoked, this :option:`cmake --build` command line will launch the
underlying build system tool.
.. versionadded:: 3.21
The ``PARALLEL_LEVEL`` argument can be used to set the
:option:`--parallel <cmake--build --parallel>` flag.
.. code-block:: cmake
build_command(<cachevariable> <makecommand>)
This second signature is deprecated, but still available for backwards
compatibility. Use the first signature instead.
It sets the given ``<cachevariable>`` to a command-line string as
above but without the :option:`--target <cmake--build --target>` option.
The ``<makecommand>`` is ignored but should be the full path to
devenv, nmake, make or one of the end user build tools
for legacy invocations.
.. note::
In CMake versions prior to 3.0 this command returned a command
line that directly invokes the native build tool for the current
generator. Their implementation of the ``PROJECT_NAME`` option
had no useful effects, so CMake now warns on use of the option.

15
cmake/share/cmake-3.30/Help/command/build_name.rst Normal file
View File

@ -0,0 +1,15 @@
build_name
----------
Disallowed since version 3.0. See CMake Policy :policy:`CMP0036`.
Use ``${CMAKE_SYSTEM}`` and ``${CMAKE_CXX_COMPILER}`` instead.
.. code-block:: cmake
build_name(variable)
Sets the specified variable to a string representing the platform and
compiler settings. These values are now available through the
:variable:`CMAKE_SYSTEM` and
:variable:`CMAKE_CXX_COMPILER <CMAKE_<LANG>_COMPILER>` variables.

78
cmake/share/cmake-3.30/Help/command/cmake_file_api.rst Normal file
View File

@ -0,0 +1,78 @@
cmake_file_api
--------------
.. versionadded:: 3.27
Enables interacting with the :manual:`CMake file API <cmake-file-api(7)>`.
.. signature::
cmake_file_api(QUERY ...)
The ``QUERY`` subcommand adds a file API query for the current CMake
invocation.
.. code-block:: cmake
cmake_file_api(
QUERY
API_VERSION <version>
[CODEMODEL <versions>...]
[CACHE <versions>...]
[CMAKEFILES <versions>...]
[TOOLCHAINS <versions>...]
)
The ``API_VERSION`` must always be given. Currently, the only supported
value for ``<version>`` is 1. See :ref:`file-api v1` for details of the
reply content and location.
Each of the optional keywords ``CODEMODEL``, ``CACHE``, ``CMAKEFILES`` and
``TOOLCHAINS`` correspond to one of the object kinds that can be requested
by the project. The ``configureLog`` object kind cannot be set with this
command, since it must be set before CMake starts reading the top level
``CMakeLists.txt`` file.
For each of the optional keywords, the ``<versions>`` list must contain one
or more version values of the form ``major`` or ``major.minor``, where
``major`` and ``minor`` are integers. Projects should list the versions they
accept in their preferred order, as only the first supported value from the
list will be selected. The command will ignore versions with a ``major``
version higher than any major version it supports for that object kind.
It will raise an error if it encounters an invalid version number, or if none
of the requested versions is supported.
For each type of object kind requested, a query equivalent to a shared,
stateless query will be added internally. No query file will be created in
the file system. The reply *will* be written to the file system at
generation time.
It is not an error to add a query for the same thing more than once, whether
from query files or from multiple calls to ``cmake_file_api(QUERY)``.
The final set of queries will be a merged combination of all queries
specified on disk and queries submitted by the project.
Example
^^^^^^^
A project may want to use replies from the file API at build time to implement
some form of verification task. Instead of relying on something outside of
CMake to create a query file, the project can use ``cmake_file_api(QUERY)``
to request the required information for the current run. It can then create
a custom command to run at build time, knowing that the requested information
should always be available.
.. code-block:: cmake
cmake_file_api(
QUERY
API_VERSION 1
CODEMODEL 2.3
TOOLCHAINS 1
)
add_custom_target(verify_project
COMMAND ${CMAKE_COMMAND}
-D BUILD_DIR=${CMAKE_BINARY_DIR}
-D CONFIG=$<CONFIG>
-P ${CMAKE_CURRENT_SOURCE_DIR}/verify_project.cmake
)

403
cmake/share/cmake-3.30/Help/command/cmake_host_system_information.rst Normal file
View File

@ -0,0 +1,403 @@
cmake_host_system_information
-----------------------------
Query various host system information.
Synopsis
^^^^^^^^
.. parsed-literal::
`Query host system specific information`_
cmake_host_system_information(RESULT <variable> QUERY <key> ...)
`Query Windows registry`_
cmake_host_system_information(RESULT <variable> QUERY WINDOWS_REGISTRY <key> ...)
Query host system specific information
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
.. code-block:: cmake
cmake_host_system_information(RESULT <variable> QUERY <key> ...)
Queries system information of the host system on which cmake runs.
One or more ``<key>`` can be provided to select the information to be
queried. The list of queried values is stored in ``<variable>``.
``<key>`` can be one of the following values:
``NUMBER_OF_LOGICAL_CORES``
Number of logical cores
``NUMBER_OF_PHYSICAL_CORES``
Number of physical cores
``HOSTNAME``
Hostname
``FQDN``
Fully qualified domain name
``TOTAL_VIRTUAL_MEMORY``
Total virtual memory in MiB [#mebibytes]_
``AVAILABLE_VIRTUAL_MEMORY``
Available virtual memory in MiB [#mebibytes]_
``TOTAL_PHYSICAL_MEMORY``
Total physical memory in MiB [#mebibytes]_
``AVAILABLE_PHYSICAL_MEMORY``
Available physical memory in MiB [#mebibytes]_
``IS_64BIT``
.. versionadded:: 3.10
One if processor is 64Bit
``HAS_FPU``
.. versionadded:: 3.10
One if processor has floating point unit
``HAS_MMX``
.. versionadded:: 3.10
One if processor supports MMX instructions
``HAS_MMX_PLUS``
.. versionadded:: 3.10
One if processor supports Ext. MMX instructions
``HAS_SSE``
.. versionadded:: 3.10
One if processor supports SSE instructions
``HAS_SSE2``
.. versionadded:: 3.10
One if processor supports SSE2 instructions
``HAS_SSE_FP``
.. versionadded:: 3.10
One if processor supports SSE FP instructions
``HAS_SSE_MMX``
.. versionadded:: 3.10
One if processor supports SSE MMX instructions
``HAS_AMD_3DNOW``
.. versionadded:: 3.10
One if processor supports 3DNow instructions
``HAS_AMD_3DNOW_PLUS``
.. versionadded:: 3.10
One if processor supports 3DNow+ instructions
``HAS_IA64``
.. versionadded:: 3.10
One if IA64 processor emulating x86
``HAS_SERIAL_NUMBER``
.. versionadded:: 3.10
One if processor has serial number
``PROCESSOR_SERIAL_NUMBER``
.. versionadded:: 3.10
Processor serial number
``PROCESSOR_NAME``
.. versionadded:: 3.10
Human readable processor name
``PROCESSOR_DESCRIPTION``
.. versionadded:: 3.10
Human readable full processor description
``OS_NAME``
.. versionadded:: 3.10
See :variable:`CMAKE_HOST_SYSTEM_NAME`
``OS_RELEASE``
.. versionadded:: 3.10
The OS sub-type e.g. on Windows ``Professional``
``OS_VERSION``
.. versionadded:: 3.10
The OS build ID
``OS_PLATFORM``
.. versionadded:: 3.10
See :variable:`CMAKE_HOST_SYSTEM_PROCESSOR`
``MSYSTEM_PREFIX``
.. versionadded:: 3.28
Available only on Windows hosts. In a MSYS or MinGW development
environment that sets the ``MSYSTEM`` environment variable, this
is its installation prefix. Otherwise, this is the empty string.
``DISTRIB_INFO``
.. versionadded:: 3.22
Read :file:`/etc/os-release` file and define the given ``<variable>``
into a list of read variables
``DISTRIB_<name>``
.. versionadded:: 3.22
Get the ``<name>`` variable (see `man 5 os-release`_) if it exists in the
:file:`/etc/os-release` file
Example:
.. code-block:: cmake
cmake_host_system_information(RESULT PRETTY_NAME QUERY DISTRIB_PRETTY_NAME)
message(STATUS "${PRETTY_NAME}")
cmake_host_system_information(RESULT DISTRO QUERY DISTRIB_INFO)
foreach(VAR IN LISTS DISTRO)
message(STATUS "${VAR}=`${${VAR}}`")
endforeach()
Output::
-- Ubuntu 20.04.2 LTS
-- DISTRO_BUG_REPORT_URL=`https://bugs.launchpad.net/ubuntu/`
-- DISTRO_HOME_URL=`https://www.ubuntu.com/`
-- DISTRO_ID=`ubuntu`
-- DISTRO_ID_LIKE=`debian`
-- DISTRO_NAME=`Ubuntu`
-- DISTRO_PRETTY_NAME=`Ubuntu 20.04.2 LTS`
-- DISTRO_PRIVACY_POLICY_URL=`https://www.ubuntu.com/legal/terms-and-policies/privacy-policy`
-- DISTRO_SUPPORT_URL=`https://help.ubuntu.com/`
-- DISTRO_UBUNTU_CODENAME=`focal`
-- DISTRO_VERSION=`20.04.2 LTS (Focal Fossa)`
-- DISTRO_VERSION_CODENAME=`focal`
-- DISTRO_VERSION_ID=`20.04`
If :file:`/etc/os-release` file is not found, the command tries to gather OS
identification via fallback scripts. The fallback script can use `various
distribution-specific files`_ to collect OS identification data and map it
into `man 5 os-release`_ variables.
Fallback Interface Variables
""""""""""""""""""""""""""""
.. variable:: CMAKE_GET_OS_RELEASE_FALLBACK_SCRIPTS
In addition to the scripts shipped with CMake, a user may append full
paths to his script(s) to the this list. The script filename has the
following format: ``NNN-<name>.cmake``, where ``NNN`` is three digits
used to apply collected scripts in a specific order.
.. variable:: CMAKE_GET_OS_RELEASE_FALLBACK_RESULT_<varname>
Variables collected by the user provided fallback script
ought to be assigned to CMake variables using this naming
convention. Example, the ``ID`` variable from the manual becomes
``CMAKE_GET_OS_RELEASE_FALLBACK_RESULT_ID``.
.. variable:: CMAKE_GET_OS_RELEASE_FALLBACK_RESULT
The fallback script ought to store names of all assigned
``CMAKE_GET_OS_RELEASE_FALLBACK_RESULT_<varname>`` variables in this list.
Example:
.. code-block:: cmake
# Try to detect some old distribution
# See also
# - http://linuxmafia.com/faq/Admin/release-files.html
#
if(NOT EXISTS "${CMAKE_SYSROOT}/etc/foobar-release")
return()
endif()
# Get the first string only
file(
STRINGS "${CMAKE_SYSROOT}/etc/foobar-release" CMAKE_GET_OS_RELEASE_FALLBACK_CONTENT
LIMIT_COUNT 1
)
#
# Example:
#
# Foobar distribution release 1.2.3 (server)
#
if(CMAKE_GET_OS_RELEASE_FALLBACK_CONTENT MATCHES "Foobar distribution release ([0-9\.]+) .*")
set(CMAKE_GET_OS_RELEASE_FALLBACK_RESULT_NAME Foobar)
set(CMAKE_GET_OS_RELEASE_FALLBACK_RESULT_PRETTY_NAME "${CMAKE_GET_OS_RELEASE_FALLBACK_CONTENT}")
set(CMAKE_GET_OS_RELEASE_FALLBACK_RESULT_ID foobar)
set(CMAKE_GET_OS_RELEASE_FALLBACK_RESULT_VERSION ${CMAKE_MATCH_1})
set(CMAKE_GET_OS_RELEASE_FALLBACK_RESULT_VERSION_ID ${CMAKE_MATCH_1})
list(
APPEND CMAKE_GET_OS_RELEASE_FALLBACK_RESULT
CMAKE_GET_OS_RELEASE_FALLBACK_RESULT_NAME
CMAKE_GET_OS_RELEASE_FALLBACK_RESULT_PRETTY_NAME
CMAKE_GET_OS_RELEASE_FALLBACK_RESULT_ID
CMAKE_GET_OS_RELEASE_FALLBACK_RESULT_VERSION
CMAKE_GET_OS_RELEASE_FALLBACK_RESULT_VERSION_ID
)
endif()
unset(CMAKE_GET_OS_RELEASE_FALLBACK_CONTENT)
.. rubric:: Footnotes
.. [#mebibytes] One MiB (mebibyte) is equal to 1024x1024 bytes.
.. _man 5 os-release: https://www.freedesktop.org/software/systemd/man/latest/os-release.html
.. _various distribution-specific files: http://linuxmafia.com/faq/Admin/release-files.html
.. _Query Windows registry:
Query Windows registry
^^^^^^^^^^^^^^^^^^^^^^
.. versionadded:: 3.24
::
cmake_host_system_information(RESULT <variable>
QUERY WINDOWS_REGISTRY <key> [VALUE_NAMES|SUBKEYS|VALUE <name>]
[VIEW (64|32|64_32|32_64|HOST|TARGET|BOTH)]
[SEPARATOR <separator>]
[ERROR_VARIABLE <result>])
Performs query operations on local computer registry subkey. Returns a list of
subkeys or value names that are located under the specified subkey in the
registry or the data of the specified value name. The result of the queried
entity is stored in ``<variable>``.
.. note::
Querying registry for any other platforms than ``Windows``, including
``CYGWIN``, will always returns an empty string and sets an error message in
the variable specified with sub-option ``ERROR_VARIABLE``.
``<key>`` specify the full path of a subkey on the local computer. The
``<key>`` must include a valid root key. Valid root keys for the local computer
are:
* ``HKLM`` or ``HKEY_LOCAL_MACHINE``
* ``HKCU`` or ``HKEY_CURRENT_USER``
* ``HKCR`` or ``HKEY_CLASSES_ROOT``
* ``HKU`` or ``HKEY_USERS``
* ``HKCC`` or ``HKEY_CURRENT_CONFIG``
And, optionally, the path to a subkey under the specified root key. The path
separator can be the slash or the backslash. ``<key>`` is not case sensitive.
For example:
.. code-block:: cmake
cmake_host_system_information(RESULT result QUERY WINDOWS_REGISTRY "HKLM")
cmake_host_system_information(RESULT result QUERY WINDOWS_REGISTRY "HKLM/SOFTWARE/Kitware")
cmake_host_system_information(RESULT result QUERY WINDOWS_REGISTRY "HKCU\\SOFTWARE\\Kitware")
``VALUE_NAMES``
Request the list of value names defined under ``<key>``. If a default value
is defined, it will be identified with the special name ``(default)``.
``SUBKEYS``
Request the list of subkeys defined under ``<key>``.
``VALUE <name>``
Request the data stored in value named ``<name>``. If ``VALUE`` is not
specified or argument is the special name ``(default)``, the content of the
default value, if any, will be returned.
.. code-block:: cmake
# query default value for HKLM/SOFTWARE/Kitware key
cmake_host_system_information(RESULT result
QUERY WINDOWS_REGISTRY "HKLM/SOFTWARE/Kitware")
# query default value for HKLM/SOFTWARE/Kitware key using special value name
cmake_host_system_information(RESULT result
QUERY WINDOWS_REGISTRY "HKLM/SOFTWARE/Kitware"
VALUE "(default)")
Supported types are:
* ``REG_SZ``.
* ``REG_EXPAND_SZ``. The returned data is expanded.
* ``REG_MULTI_SZ``. The returned is expressed as a CMake list. See also
``SEPARATOR`` sub-option.
* ``REG_DWORD``.
* ``REG_QWORD``.
For all other types, an empty string is returned.
``VIEW``
Specify which registry views must be queried. When not specified, ``BOTH``
view is used.
``64``
Query the 64bit registry. On ``32bit Windows``, returns always an empty
string.
``32``
Query the 32bit registry.
``64_32``
For ``VALUE`` sub-option or default value, query the registry using view
``64``, and if the request failed, query the registry using view ``32``.
For ``VALUE_NAMES`` and ``SUBKEYS`` sub-options, query both views (``64``
and ``32``) and merge the results (sorted and duplicates removed).
``32_64``
For ``VALUE`` sub-option or default value, query the registry using view
``32``, and if the request failed, query the registry using view ``64``.
For ``VALUE_NAMES`` and ``SUBKEYS`` sub-options, query both views (``32``
and ``64``) and merge the results (sorted and duplicates removed).
``HOST``
Query the registry matching the architecture of the host: ``64`` on ``64bit
Windows`` and ``32`` on ``32bit Windows``.
``TARGET``
Query the registry matching the architecture specified by
:variable:`CMAKE_SIZEOF_VOID_P` variable. If not defined, fallback to
``HOST`` view.
``BOTH``
Query both views (``32`` and ``64``). The order depends of the following
rules: If :variable:`CMAKE_SIZEOF_VOID_P` variable is defined. Use the
following view depending of the content of this variable:
* ``8``: ``64_32``
* ``4``: ``32_64``
If :variable:`CMAKE_SIZEOF_VOID_P` variable is not defined, rely on
architecture of the host:
* ``64bit``: ``64_32``
* ``32bit``: ``32``
``SEPARATOR``
Specify the separator character for ``REG_MULTI_SZ`` type. When not
specified, the character ``\0`` is used.
``ERROR_VARIABLE <result>``
Returns any error raised during query operation. In case of success, the
variable holds an empty string.

536
cmake/share/cmake-3.30/Help/command/cmake_language.rst Normal file
View File

@ -0,0 +1,536 @@
cmake_language
--------------
.. versionadded:: 3.18
Call meta-operations on CMake commands.
Synopsis
^^^^^^^^
.. parsed-literal::
cmake_language(`CALL`_ <command> [<arg>...])
cmake_language(`EVAL`_ CODE <code>...)
cmake_language(`DEFER`_ <options>... CALL <command> [<arg>...])
cmake_language(`SET_DEPENDENCY_PROVIDER`_ <command> SUPPORTED_METHODS <methods>...)
cmake_language(`GET_MESSAGE_LOG_LEVEL`_ <out-var>)
cmake_language(`EXIT`_ <exit-code>)
Introduction
^^^^^^^^^^^^
This command will call meta-operations on built-in CMake commands or
those created via the :command:`macro` or :command:`function` commands.
``cmake_language`` does not introduce a new variable or policy scope.
Calling Commands
^^^^^^^^^^^^^^^^
.. signature::
cmake_language(CALL <command> [<arg>...])
Calls the named ``<command>`` with the given arguments (if any).
For example, the code:
.. code-block:: cmake
set(message_command "message")
cmake_language(CALL ${message_command} STATUS "Hello World!")
is equivalent to
.. code-block:: cmake
message(STATUS "Hello World!")
.. note::
To ensure consistency of the code, the following commands are not allowed:
* ``if`` / ``elseif`` / ``else`` / ``endif``
* ``block`` / ``endblock``
* ``while`` / ``endwhile``
* ``foreach`` / ``endforeach``
* ``function`` / ``endfunction``
* ``macro`` / ``endmacro``
Evaluating Code
^^^^^^^^^^^^^^^
.. signature::
cmake_language(EVAL CODE <code>...)
:target: EVAL
Evaluates the ``<code>...`` as CMake code.
For example, the code:
.. code-block:: cmake
set(A TRUE)
set(B TRUE)
set(C TRUE)
set(condition "(A AND B) OR C")
cmake_language(EVAL CODE "
if (${condition})
message(STATUS TRUE)
else()
message(STATUS FALSE)
endif()"
)
is equivalent to
.. code-block:: cmake
set(A TRUE)
set(B TRUE)
set(C TRUE)
set(condition "(A AND B) OR C")
file(WRITE ${CMAKE_CURRENT_BINARY_DIR}/eval.cmake "
if (${condition})
message(STATUS TRUE)
else()
message(STATUS FALSE)
endif()"
)
include(${CMAKE_CURRENT_BINARY_DIR}/eval.cmake)
Deferring Calls
^^^^^^^^^^^^^^^
.. versionadded:: 3.19
.. signature::
cmake_language(DEFER <options>... CALL <command> [<arg>...])
Schedules a call to the named ``<command>`` with the given arguments (if any)
to occur at a later time. By default, deferred calls are executed as if
written at the end of the current directory's ``CMakeLists.txt`` file,
except that they run even after a :command:`return` call. Variable
references in arguments are evaluated at the time the deferred call is
executed.
The options are:
``DIRECTORY <dir>``
Schedule the call for the end of the given directory instead of the
current directory. The ``<dir>`` may reference either a source
directory or its corresponding binary directory. Relative paths are
treated as relative to the current source directory.
The given directory must be known to CMake, being either the top-level
directory or one added by :command:`add_subdirectory`. Furthermore,
the given directory must not yet be finished processing. This means
it can be the current directory or one of its ancestors.
``ID <id>``
Specify an identification for the deferred call.
The ``<id>`` may not be empty and may not begin with a capital letter ``A-Z``.
The ``<id>`` may begin with an underscore (``_``) only if it was generated
automatically by an earlier call that used ``ID_VAR`` to get the id.
``ID_VAR <var>``
Specify a variable in which to store the identification for the
deferred call. If ``ID <id>`` is not given, a new identification
will be generated and the generated id will start with an underscore (``_``).
The currently scheduled list of deferred calls may be retrieved:
.. code-block:: cmake
cmake_language(DEFER [DIRECTORY <dir>] GET_CALL_IDS <var>)
This will store in ``<var>`` a :ref:`semicolon-separated list <CMake Language
Lists>` of deferred call ids. The ids are for the directory scope in which
the calls have been deferred to (i.e. where they will be executed), which can
be different to the scope in which they were created. The ``DIRECTORY``
option can be used to specify the scope for which to retrieve the call ids.
If that option is not given, the call ids for the current directory scope
will be returned.
Details of a specific call may be retrieved from its id:
.. code-block:: cmake
cmake_language(DEFER [DIRECTORY <dir>] GET_CALL <id> <var>)
This will store in ``<var>`` a :ref:`semicolon-separated list <CMake Language
Lists>` in which the first element is the name of the command to be
called, and the remaining elements are its unevaluated arguments (any
contained ``;`` characters are included literally and cannot be distinguished
from multiple arguments). If multiple calls are scheduled with the same id,
this retrieves the first one. If no call is scheduled with the given id in
the specified ``DIRECTORY`` scope (or the current directory scope if no
``DIRECTORY`` option is given), this stores an empty string in the variable.
Deferred calls may be canceled by their id:
.. code-block:: cmake
cmake_language(DEFER [DIRECTORY <dir>] CANCEL_CALL <id>...)
This cancels all deferred calls matching any of the given ids in the specified
``DIRECTORY`` scope (or the current directory scope if no ``DIRECTORY`` option
is given). Unknown ids are silently ignored.
Deferred Call Examples
""""""""""""""""""""""
For example, the code:
.. code-block:: cmake
cmake_language(DEFER CALL message "${deferred_message}")
cmake_language(DEFER ID_VAR id CALL message "Canceled Message")
cmake_language(DEFER CANCEL_CALL ${id})
message("Immediate Message")
set(deferred_message "Deferred Message")
prints::
Immediate Message
Deferred Message
The ``Canceled Message`` is never printed because its command is
canceled. The ``deferred_message`` variable reference is not evaluated
until the call site, so it can be set after the deferred call is scheduled.
In order to evaluate variable references immediately when scheduling a
deferred call, wrap it using ``cmake_language(EVAL)``. However, note that
arguments will be re-evaluated in the deferred call, though that can be
avoided by using bracket arguments. For example:
.. code-block:: cmake
set(deferred_message "Deferred Message 1")
set(re_evaluated [[${deferred_message}]])
cmake_language(EVAL CODE "
cmake_language(DEFER CALL message [[${deferred_message}]])
cmake_language(DEFER CALL message \"${re_evaluated}\")
")
message("Immediate Message")
set(deferred_message "Deferred Message 2")
also prints::
Immediate Message
Deferred Message 1
Deferred Message 2
.. _dependency_providers:
Dependency Providers
^^^^^^^^^^^^^^^^^^^^
.. versionadded:: 3.24
.. note:: A high-level introduction to this feature can be found in the
:ref:`Using Dependencies Guide <dependency_providers_overview>`.
.. signature::
cmake_language(SET_DEPENDENCY_PROVIDER <command>
SUPPORTED_METHODS <methods>...)
When a call is made to :command:`find_package` or
:command:`FetchContent_MakeAvailable`, the call may be forwarded to a
dependency provider which then has the opportunity to fulfill the request.
If the request is for one of the ``<methods>`` specified when the provider
was set, CMake calls the provider's ``<command>`` with a set of
method-specific arguments. If the provider does not fulfill the request,
or if the provider doesn't support the request's method, or no provider
is set, the built-in :command:`find_package` or
:command:`FetchContent_MakeAvailable` implementation is used to fulfill
the request in the usual way.
One or more of the following values can be specified for the ``<methods>``
when setting the provider:
``FIND_PACKAGE``
The provider command accepts :command:`find_package` requests.
``FETCHCONTENT_MAKEAVAILABLE_SERIAL``
The provider command accepts :command:`FetchContent_MakeAvailable`
requests. It expects each dependency to be fed to the provider command
one at a time, not the whole list in one go.
Only one provider can be set at any point in time. If a provider is already
set when ``cmake_language(SET_DEPENDENCY_PROVIDER)`` is called, the new
provider replaces the previously set one. The specified ``<command>`` must
already exist when ``cmake_language(SET_DEPENDENCY_PROVIDER)`` is called.
As a special case, providing an empty string for the ``<command>`` and no
``<methods>`` will discard any previously set provider.
The dependency provider can only be set while processing one of the files
specified by the :variable:`CMAKE_PROJECT_TOP_LEVEL_INCLUDES` variable.
Thus, dependency providers can only be set as part of the first call to
:command:`project`. Calling ``cmake_language(SET_DEPENDENCY_PROVIDER)``
outside of that context will result in an error.
.. versionadded:: 3.30
The :prop_gbl:`PROPAGATE_TOP_LEVEL_INCLUDES_TO_TRY_COMPILE` global
property can be set if the dependency provider also wants to be enabled
in whole-project calls to :command:`try_compile`.
.. note::
The choice of dependency provider should always be under the user's control.
As a convenience, a project may choose to provide a file that users can
list in their :variable:`CMAKE_PROJECT_TOP_LEVEL_INCLUDES` variable, but
the use of such a file should always be the user's choice.
Provider commands
"""""""""""""""""
Providers define a single ``<command>`` to accept requests. The name of
the command should be specific to that provider, not something overly
generic that another provider might also use. This enables users to compose
different providers in their own custom provider. The recommended form is
``xxx_provide_dependency()``, where ``xxx`` is the provider-specific part
(e.g. ``vcpkg_provide_dependency()``, ``conan_provide_dependency()``,
``ourcompany_provide_dependency()``, and so on).
.. code-block:: cmake
xxx_provide_dependency(<method> [<method-specific-args>...])
Because some methods expect certain variables to be set in the calling scope,
the provider command should typically be implemented as a macro rather than a
function. This ensures it does not introduce a new variable scope.
The arguments CMake passes to the dependency provider depend on the type of
request. The first argument is always the method, and it will only ever
be one of the ``<methods>`` that was specified when setting the provider.
``FIND_PACKAGE``
The ``<method-specific-args>`` will be everything passed to the
:command:`find_package` call that requested the dependency. The first of
these ``<method-specific-args>`` will therefore always be the name of the
dependency. Dependency names are case-sensitive for this method because
:command:`find_package` treats them case-sensitively too.
If the provider command fulfills the request, it must set the same variable
that :command:`find_package` expects to be set. For a dependency named
``depName``, the provider must set ``depName_FOUND`` to true if it fulfilled
the request. If the provider returns without setting this variable, CMake
will assume the request was not fulfilled and will fall back to the
built-in implementation.
If the provider needs to call the built-in :command:`find_package`
implementation as part of its processing, it can do so by including the
``BYPASS_PROVIDER`` keyword as one of the arguments.
``FETCHCONTENT_MAKEAVAILABLE_SERIAL``
The ``<method-specific-args>`` will be everything passed to the
:command:`FetchContent_Declare` call that corresponds to the requested
dependency, with the following exceptions:
* If ``SOURCE_DIR`` or ``BINARY_DIR`` were not part of the original
declared arguments, they will be added with their default values.
* If :variable:`FETCHCONTENT_TRY_FIND_PACKAGE_MODE` is set to ``NEVER``,
any ``FIND_PACKAGE_ARGS`` will be omitted.
* The ``OVERRIDE_FIND_PACKAGE`` keyword is always omitted.
The first of the ``<method-specific-args>`` will always be the name of the
dependency. Dependency names are case-insensitive for this method because
:module:`FetchContent` also treats them case-insensitively.
If the provider fulfills the request, it should call
:command:`FetchContent_SetPopulated`, passing the name of the dependency as
the first argument. The ``SOURCE_DIR`` and ``BINARY_DIR`` arguments to that
command should only be given if the provider makes the dependency's source
and build directories available in exactly the same way as the built-in
:command:`FetchContent_MakeAvailable` command.
If the provider returns without calling :command:`FetchContent_SetPopulated`
for the named dependency, CMake will assume the request was not fulfilled
and will fall back to the built-in implementation.
Note that empty arguments may be significant for this method (e.g. an empty
string following a ``GIT_SUBMODULES`` keyword). Therefore, if forwarding
these arguments on to another command, extra care must be taken to avoid such
arguments being silently dropped.
If ``FETCHCONTENT_SOURCE_DIR_<uppercaseDepName>`` is set, then the
dependency provider will never see requests for the ``<depName>`` dependency
for this method. When the user sets such a variable, they are explicitly
overriding where to get that dependency from and are taking on the
responsibility that their overriding version meets any requirements for that
dependency and is compatible with whatever else in the project uses it.
Depending on the value of :variable:`FETCHCONTENT_TRY_FIND_PACKAGE_MODE`
and whether the ``OVERRIDE_FIND_PACKAGE`` option was given to
:command:`FetchContent_Declare`, having
``FETCHCONTENT_SOURCE_DIR_<uppercaseDepName>`` set may also prevent the
dependency provider from seeing requests for a ``find_package(depName)``
call too.
Provider Examples
"""""""""""""""""
This first example only intercepts :command:`find_package` calls. The
provider command runs an external tool which copies the relevant artifacts
into a provider-specific directory, if that tool knows about the dependency.
It then relies on the built-in implementation to then find those artifacts.
:command:`FetchContent_MakeAvailable` calls would not go through the provider.
.. code-block:: cmake
:caption: mycomp_provider.cmake
# Always ensure we have the policy settings this provider expects
cmake_minimum_required(VERSION 3.24)
set(MYCOMP_PROVIDER_INSTALL_DIR ${CMAKE_BINARY_DIR}/mycomp_packages
CACHE PATH "The directory this provider installs packages to"
)
# Tell the built-in implementation to look in our area first, unless
# the find_package() call uses NO_..._PATH options to exclude it
list(APPEND CMAKE_MODULE_PATH ${MYCOMP_PROVIDER_INSTALL_DIR}/cmake)
list(APPEND CMAKE_PREFIX_PATH ${MYCOMP_PROVIDER_INSTALL_DIR})
macro(mycomp_provide_dependency method package_name)
execute_process(
COMMAND some_tool ${package_name} --installdir ${MYCOMP_PROVIDER_INSTALL_DIR}
COMMAND_ERROR_IS_FATAL ANY
)
endmacro()
cmake_language(
SET_DEPENDENCY_PROVIDER mycomp_provide_dependency
SUPPORTED_METHODS FIND_PACKAGE
)
The user would then typically use the above file like so::
cmake -DCMAKE_PROJECT_TOP_LEVEL_INCLUDES=/path/to/mycomp_provider.cmake ...
The next example demonstrates a provider that accepts both methods, but
only handles one specific dependency. It enforces providing Google Test
using :module:`FetchContent`, but leaves all other dependencies to be
fulfilled by CMake's built-in implementation. It accepts a few different
names, which demonstrates one way of working around projects that hard-code
an unusual or undesirable way of adding this particular dependency to the
build. The example also demonstrates how to use the :command:`list` command
to preserve variables that may be overwritten by a call to
:command:`FetchContent_MakeAvailable`.
.. code-block:: cmake
:caption: mycomp_provider.cmake
cmake_minimum_required(VERSION 3.24)
# Because we declare this very early, it will take precedence over any
# details the project might declare later for the same thing
include(FetchContent)
FetchContent_Declare(
googletest
GIT_REPOSITORY https://github.com/google/googletest.git
GIT_TAG e2239ee6043f73722e7aa812a459f54a28552929 # release-1.11.0
)
# Both FIND_PACKAGE and FETCHCONTENT_MAKEAVAILABLE_SERIAL methods provide
# the package or dependency name as the first method-specific argument.
macro(mycomp_provide_dependency method dep_name)
if("${dep_name}" MATCHES "^(gtest|googletest)$")
# Save our current command arguments in case we are called recursively
list(APPEND mycomp_provider_args ${method} ${dep_name})
# This will forward to the built-in FetchContent implementation,
# which detects a recursive call for the same thing and avoids calling
# the provider again if dep_name is the same as the current call.
FetchContent_MakeAvailable(googletest)
# Restore our command arguments
list(POP_BACK mycomp_provider_args dep_name method)
# Tell the caller we fulfilled the request
if("${method}" STREQUAL "FIND_PACKAGE")
# We need to set this if we got here from a find_package() call
# since we used a different method to fulfill the request.
# This example assumes projects only use the gtest targets,
# not any of the variables the FindGTest module may define.
set(${dep_name}_FOUND TRUE)
elseif(NOT "${dep_name}" STREQUAL "googletest")
# We used the same method, but were given a different name to the
# one we populated with. Tell the caller about the name it used.
FetchContent_SetPopulated(${dep_name}
SOURCE_DIR "${googletest_SOURCE_DIR}"
BINARY_DIR "${googletest_BINARY_DIR}"
)
endif()
endif()
endmacro()
cmake_language(
SET_DEPENDENCY_PROVIDER mycomp_provide_dependency
SUPPORTED_METHODS
FIND_PACKAGE
FETCHCONTENT_MAKEAVAILABLE_SERIAL
)
The final example demonstrates how to modify arguments to a
:command:`find_package` call. It forces all such calls to have the
``QUIET`` keyword. It uses the ``BYPASS_PROVIDER`` keyword to prevent
calling the provider command recursively for the same dependency.
.. code-block:: cmake
:caption: mycomp_provider.cmake
cmake_minimum_required(VERSION 3.24)
macro(mycomp_provide_dependency method)
find_package(${ARGN} BYPASS_PROVIDER QUIET)
endmacro()
cmake_language(
SET_DEPENDENCY_PROVIDER mycomp_provide_dependency
SUPPORTED_METHODS FIND_PACKAGE
)
Getting current message log level
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
.. versionadded:: 3.25
.. _query_message_log_level:
.. signature::
cmake_language(GET_MESSAGE_LOG_LEVEL <output_variable>)
Writes the current :command:`message` logging level
into the given ``<output_variable>``.
See :command:`message` for the possible logging levels.
The current message logging level can be set either using the
:option:`--log-level <cmake --log-level>`
command line option of the :manual:`cmake(1)` program or using
the :variable:`CMAKE_MESSAGE_LOG_LEVEL` variable.
If both the command line option and the variable are set, the command line
option takes precedence. If neither are set, the default logging level
is returned.
Terminating Scripts
^^^^^^^^^^^^^^^^^^^
.. versionadded:: 3.29
.. signature::
cmake_language(EXIT <exit-code>)
Terminate the current :option:`cmake -P` script and exit with ``<exit-code>``.
This command works only in :ref:`script mode <Script Processing Mode>`.
If used outside of that context, it will cause a fatal error.
The ``<exit-code>`` should be non-negative.
If ``<exit-code>`` is negative, then the behavior
is unspecified (e.g., on Windows the error code -1
becomes ``0xffffffff``, and on Linux it becomes 255).
Exit codes above 255 may not be supported by the underlying
shell or platform, and some shells may interpret values
above 125 specially. Therefore, it is advisable to only
specify an ``<exit-code>`` in the range 0 to 125.

88
cmake/share/cmake-3.30/Help/command/cmake_minimum_required.rst Normal file
View File

@ -0,0 +1,88 @@
cmake_minimum_required
----------------------
Require a minimum version of cmake.
.. code-block:: cmake
cmake_minimum_required(VERSION <min>[...<policy_max>] [FATAL_ERROR])
.. versionadded:: 3.12
The optional ``<policy_max>`` version.
Sets the minimum required version of cmake for a project.
Also updates the policy settings as explained below.
``<min>`` and the optional ``<policy_max>`` are each CMake versions of the
form ``major.minor[.patch[.tweak]]``, and the ``...`` is literal.
If the running version of CMake is lower than the ``<min>`` required
version it will stop processing the project and report an error.
The optional ``<policy_max>`` version, if specified, must be at least the
``<min>`` version and affects policy settings as described in `Policy Settings`_.
If the running version of CMake is older than 3.12, the extra ``...``
dots will be seen as version component separators, resulting in the
``...<max>`` part being ignored and preserving the pre-3.12 behavior
of basing policies on ``<min>``.
This command will set the value of the
:variable:`CMAKE_MINIMUM_REQUIRED_VERSION` variable to ``<min>``.
The ``FATAL_ERROR`` option is accepted but ignored by CMake 2.6 and
higher. It should be specified so CMake versions 2.4 and lower fail
with an error instead of just a warning.
.. note::
Call the ``cmake_minimum_required()`` command at the beginning of
the top-level ``CMakeLists.txt`` file even before calling the
:command:`project` command. It is important to establish version
and policy settings before invoking other commands whose behavior
they may affect. See also policy :policy:`CMP0000`.
Calling ``cmake_minimum_required()`` inside a :command:`function`
limits some effects to the function scope when invoked. For example,
the :variable:`CMAKE_MINIMUM_REQUIRED_VERSION` variable won't be set
in the calling scope. Functions do not introduce their own policy
scope though, so policy settings of the caller *will* be affected
(see below). Due to this mix of things that do and do not affect the
calling scope, calling ``cmake_minimum_required()`` inside a function
is generally discouraged.
.. _`Policy Settings`:
Policy Settings
^^^^^^^^^^^^^^^
The ``cmake_minimum_required(VERSION)`` command implicitly invokes the
:command:`cmake_policy(VERSION)` command to specify that the current
project code is written for the given range of CMake versions.
All policies known to the running version of CMake and introduced
in the ``<min>`` (or ``<max>``, if specified) version or earlier will
be set to use ``NEW`` behavior. All policies introduced in later
versions will be unset. This effectively requests behavior preferred
as of a given CMake version and tells newer CMake versions to warn
about their new policies.
When a ``<min>`` version higher than 2.4 is specified the command
implicitly invokes
.. code-block:: cmake
cmake_policy(VERSION <min>[...<max>])
which sets CMake policies based on the range of versions specified.
When a ``<min>`` version 2.4 or lower is given the command implicitly
invokes
.. code-block:: cmake
cmake_policy(VERSION 2.4[...<max>])
which enables compatibility features for CMake 2.4 and lower.
.. include:: DEPRECATED_POLICY_VERSIONS.txt
See Also
^^^^^^^^
* :command:`cmake_policy`

121
cmake/share/cmake-3.30/Help/command/cmake_parse_arguments.rst Normal file
View File

@ -0,0 +1,121 @@
cmake_parse_arguments
---------------------
Parse function or macro arguments.
.. code-block:: cmake
cmake_parse_arguments(<prefix> <options> <one_value_keywords>
<multi_value_keywords> <args>...)
cmake_parse_arguments(PARSE_ARGV <N> <prefix> <options>
<one_value_keywords> <multi_value_keywords>)
.. versionadded:: 3.5
This command is implemented natively. Previously, it has been defined in the
module :module:`CMakeParseArguments`.
This command is for use in macros or functions.
It processes the arguments given to that macro or function,
and defines a set of variables which hold the values of the
respective options.
The first signature reads processes arguments passed in the ``<args>...``.
This may be used in either a :command:`macro` or a :command:`function`.
.. versionadded:: 3.7
The ``PARSE_ARGV`` signature is only for use in a :command:`function`
body. In this case the arguments that are parsed come from the
``ARGV#`` variables of the calling function. The parsing starts with
the ``<N>``-th argument, where ``<N>`` is an unsigned integer.
This allows for the values to have special characters like ``;`` in them.
The ``<options>`` argument contains all options for the respective macro,
i.e. keywords which can be used when calling the macro without any value
following, like e.g. the ``OPTIONAL`` keyword of the :command:`install`
command.
The ``<one_value_keywords>`` argument contains all keywords for this macro
which are followed by one value, like e.g. ``DESTINATION`` keyword of the
:command:`install` command.
The ``<multi_value_keywords>`` argument contains all keywords for this
macro which can be followed by more than one value, like e.g. the
``TARGETS`` or ``FILES`` keywords of the :command:`install` command.
.. versionchanged:: 3.5
All keywords shall be unique. I.e. every keyword shall only be specified
once in either ``<options>``, ``<one_value_keywords>`` or
``<multi_value_keywords>``. A warning will be emitted if uniqueness is
violated.
When done, ``cmake_parse_arguments`` will consider for each of the
keywords listed in ``<options>``, ``<one_value_keywords>`` and
``<multi_value_keywords>`` a variable composed of the given ``<prefix>``
followed by ``"_"`` and the name of the respective keyword. These
variables will then hold the respective value from the argument list
or be undefined if the associated option could not be found.
For the ``<options>`` keywords, these will always be defined,
to ``TRUE`` or ``FALSE``, whether the option is in the argument list or not.
All remaining arguments are collected in a variable
``<prefix>_UNPARSED_ARGUMENTS`` that will be undefined if all arguments
were recognized. This can be checked afterwards to see
whether your macro was called with unrecognized parameters.
.. versionadded:: 3.15
``<one_value_keywords>`` and ``<multi_value_keywords>`` that were given no
values at all are collected in a variable
``<prefix>_KEYWORDS_MISSING_VALUES`` that will be undefined if all keywords
received values. This can be checked to see if there were keywords without
any values given.
Consider the following example macro, ``my_install()``, which takes similar
arguments to the real :command:`install` command:
.. code-block:: cmake
macro(my_install)
set(options OPTIONAL FAST)
set(oneValueArgs DESTINATION RENAME)
set(multiValueArgs TARGETS CONFIGURATIONS)
cmake_parse_arguments(MY_INSTALL "${options}" "${oneValueArgs}"
"${multiValueArgs}" ${ARGN} )
# ...
Assume ``my_install()`` has been called like this:
.. code-block:: cmake
my_install(TARGETS foo bar DESTINATION bin OPTIONAL blub CONFIGURATIONS)
After the ``cmake_parse_arguments`` call the macro will have set or undefined
the following variables::
MY_INSTALL_OPTIONAL = TRUE
MY_INSTALL_FAST = FALSE # was not used in call to my_install
MY_INSTALL_DESTINATION = "bin"
MY_INSTALL_RENAME <UNDEFINED> # was not used
MY_INSTALL_TARGETS = "foo;bar"
MY_INSTALL_CONFIGURATIONS <UNDEFINED> # was not used
MY_INSTALL_UNPARSED_ARGUMENTS = "blub" # nothing expected after "OPTIONAL"
MY_INSTALL_KEYWORDS_MISSING_VALUES = "CONFIGURATIONS"
# No value for "CONFIGURATIONS" given
You can then continue and process these variables.
Keywords terminate lists of values, e.g. if directly after a
``one_value_keyword`` another recognized keyword follows, this is
interpreted as the beginning of the new option. E.g.
``my_install(TARGETS foo DESTINATION OPTIONAL)`` would result in
``MY_INSTALL_DESTINATION`` set to ``"OPTIONAL"``, but as ``OPTIONAL``
is a keyword itself ``MY_INSTALL_DESTINATION`` will be empty (but added
to ``MY_INSTALL_KEYWORDS_MISSING_VALUES``) and ``MY_INSTALL_OPTIONAL`` will
therefore be set to ``TRUE``.
See Also
^^^^^^^^
* :command:`function`
* :command:`macro`

798
cmake/share/cmake-3.30/Help/command/cmake_path.rst Normal file
View File

@ -0,0 +1,798 @@
cmake_path
----------
.. versionadded:: 3.20
This command is for the manipulation of paths. Only syntactic aspects of
paths are handled, there is no interaction of any kind with any underlying
file system. The path may represent a non-existing path or even one that
is not allowed to exist on the current file system or platform.
For operations that do interact with the filesystem, see the :command:`file`
command.
.. note::
The ``cmake_path`` command handles paths in the format of the build system
(i.e. the host platform), not the target system. When cross-compiling,
if the path contains elements that are not representable on the host
platform (e.g. a drive letter when the host is not Windows), the results
will be unpredictable.
Synopsis
^^^^^^^^
.. parsed-literal::
`Conventions`_
`Path Structure And Terminology`_
`Normalization`_
`Decomposition`_
cmake_path(`GET`_ <path-var> :ref:`ROOT_NAME <GET_ROOT_NAME>` <out-var>)
cmake_path(`GET`_ <path-var> :ref:`ROOT_DIRECTORY <GET_ROOT_DIRECTORY>` <out-var>)
cmake_path(`GET`_ <path-var> :ref:`ROOT_PATH <GET_ROOT_PATH>` <out-var>)
cmake_path(`GET`_ <path-var> :ref:`FILENAME <GET_FILENAME>` <out-var>)
cmake_path(`GET`_ <path-var> :ref:`EXTENSION <GET_EXTENSION>` [LAST_ONLY] <out-var>)
cmake_path(`GET`_ <path-var> :ref:`STEM <GET_STEM>` [LAST_ONLY] <out-var>)
cmake_path(`GET`_ <path-var> :ref:`RELATIVE_PART <GET_RELATIVE_PART>` <out-var>)
cmake_path(`GET`_ <path-var> :ref:`PARENT_PATH <GET_PARENT_PATH>` <out-var>)
`Query`_
cmake_path(`HAS_ROOT_NAME`_ <path-var> <out-var>)
cmake_path(`HAS_ROOT_DIRECTORY`_ <path-var> <out-var>)
cmake_path(`HAS_ROOT_PATH`_ <path-var> <out-var>)
cmake_path(`HAS_FILENAME`_ <path-var> <out-var>)
cmake_path(`HAS_EXTENSION`_ <path-var> <out-var>)
cmake_path(`HAS_STEM`_ <path-var> <out-var>)
cmake_path(`HAS_RELATIVE_PART`_ <path-var> <out-var>)
cmake_path(`HAS_PARENT_PATH`_ <path-var> <out-var>)
cmake_path(`IS_ABSOLUTE`_ <path-var> <out-var>)
cmake_path(`IS_RELATIVE`_ <path-var> <out-var>)
cmake_path(`IS_PREFIX`_ <path-var> <input> [NORMALIZE] <out-var>)
cmake_path(`COMPARE`_ <input1> <OP> <input2> <out-var>)
`Modification`_
cmake_path(:ref:`SET <cmake_path-SET>` <path-var> [NORMALIZE] <input>)
cmake_path(`APPEND`_ <path-var> [<input>...] [OUTPUT_VARIABLE <out-var>])
cmake_path(`APPEND_STRING`_ <path-var> [<input>...] [OUTPUT_VARIABLE <out-var>])
cmake_path(`REMOVE_FILENAME`_ <path-var> [OUTPUT_VARIABLE <out-var>])
cmake_path(`REPLACE_FILENAME`_ <path-var> <input> [OUTPUT_VARIABLE <out-var>])
cmake_path(`REMOVE_EXTENSION`_ <path-var> [LAST_ONLY] [OUTPUT_VARIABLE <out-var>])
cmake_path(`REPLACE_EXTENSION`_ <path-var> [LAST_ONLY] <input> [OUTPUT_VARIABLE <out-var>])
`Generation`_
cmake_path(`NORMAL_PATH`_ <path-var> [OUTPUT_VARIABLE <out-var>])
cmake_path(`RELATIVE_PATH`_ <path-var> [BASE_DIRECTORY <input>] [OUTPUT_VARIABLE <out-var>])
cmake_path(`ABSOLUTE_PATH`_ <path-var> [BASE_DIRECTORY <input>] [NORMALIZE] [OUTPUT_VARIABLE <out-var>])
`Native Conversion`_
cmake_path(`NATIVE_PATH`_ <path-var> [NORMALIZE] <out-var>)
cmake_path(`CONVERT`_ <input> `TO_CMAKE_PATH_LIST`_ <out-var> [NORMALIZE])
cmake_path(`CONVERT`_ <input> `TO_NATIVE_PATH_LIST`_ <out-var> [NORMALIZE])
`Hashing`_
cmake_path(`HASH`_ <path-var> <out-var>)
Conventions
^^^^^^^^^^^
The following conventions are used in this command's documentation:
``<path-var>``
Always the name of a variable. For commands that expect a ``<path-var>``
as input, the variable must exist and it is expected to hold a single path.
``<input>``
A string literal which may contain a path, path fragment, or multiple paths
with a special separator depending on the command. See the description of
each command to see how this is interpreted.
``<input>...``
Zero or more string literal arguments.
``<out-var>``
The name of a variable into which the result of a command will be written.
.. _Path Structure And Terminology:
Path Structure And Terminology
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
A path has the following structure (all components are optional, with some
constraints):
::
root-name root-directory-separator (item-name directory-separator)* filename
``root-name``
Identifies the root on a filesystem with multiple roots (such as ``"C:"``
or ``"//myserver"``). It is optional.
``root-directory-separator``
A directory separator that, if present, indicates that this path is
absolute. If it is missing and the first element other than the
``root-name`` is an ``item-name``, then the path is relative.
``item-name``
A sequence of characters that aren't directory separators. This name may
identify a file, a hard link, a symbolic link, or a directory. Two special
cases are recognized:
* The item name consisting of a single dot character ``.`` is a
directory name that refers to the current directory.
* The item name consisting of two dot characters ``..`` is a
directory name that refers to the parent directory.
The ``(...)*`` pattern shown above is to indicate that there can be zero
or more item names, with multiple items separated by a
``directory-separator``. The ``()*`` characters are not part of the path.
``directory-separator``
The only recognized directory separator is a forward slash character ``/``.
If this character is repeated, it is treated as a single directory
separator. In other words, ``/usr///////lib`` is the same as ``/usr/lib``.
.. _FILENAME_DEF:
.. _EXTENSION_DEF:
.. _STEM_DEF:
``filename``
A path has a ``filename`` if it does not end with a ``directory-separator``.
The ``filename`` is effectively the last ``item-name`` of the path, so it
can also be a hard link, symbolic link or a directory.
A ``filename`` can have an *extension*. By default, the extension is
defined as the sub-string beginning at the left-most period (including
the period) and until the end of the ``filename``. In commands that
accept a ``LAST_ONLY`` keyword, ``LAST_ONLY`` changes the interpretation
to the sub-string beginning at the right-most period.
The following exceptions apply to the above interpretation:
* If the first character in the ``filename`` is a period, that period is
ignored (i.e. a ``filename`` like ``".profile"`` is treated as having
no extension).
* If the ``filename`` is either ``.`` or ``..``, it has no extension.
The *stem* is the part of the ``filename`` before the extension.
Some commands refer to a ``root-path``. This is the concatenation of
``root-name`` and ``root-directory-separator``, either or both of which can
be empty. A ``relative-part`` refers to the full path with any ``root-path``
removed.
Creating A Path Variable
^^^^^^^^^^^^^^^^^^^^^^^^
While a path can be created with care using an ordinary :command:`set`
command, it is recommended to use :ref:`cmake_path(SET) <cmake_path-SET>`
instead, as it automatically converts the path to the required form where
required. The :ref:`cmake_path(APPEND) <APPEND>` subcommand may
be another suitable alternative where a path needs to be constructed by
joining fragments. The following example compares the three methods for
constructing the same path:
.. code-block:: cmake
set(path1 "${CMAKE_CURRENT_SOURCE_DIR}/data")
cmake_path(SET path2 "${CMAKE_CURRENT_SOURCE_DIR}/data")
cmake_path(APPEND path3 "${CMAKE_CURRENT_SOURCE_DIR}" "data")
`Modification`_ and `Generation`_ sub-commands can either store the result
in-place, or in a separate variable named after an ``OUTPUT_VARIABLE``
keyword. All other sub-commands store the result in a mandatory ``<out-var>``
variable.
.. _Normalization:
Normalization
^^^^^^^^^^^^^
Some sub-commands support *normalizing* a path. The algorithm used to
normalize a path is as follows:
1. If the path is empty, stop (the normalized form of an empty path is
also an empty path).
2. Replace each ``directory-separator``, which may consist of multiple
separators, with a single ``/`` (``/a///b --> /a/b``).
3. Remove each solitary period (``.``) and any immediately following
``directory-separator`` (``/a/./b/. --> /a/b``).
4. Remove each ``item-name`` (other than ``..``) that is immediately
followed by a ``directory-separator`` and a ``..``, along with any
immediately following ``directory-separator`` (``/a/b/../c --> a/c``).
5. If there is a ``root-directory``, remove any ``..`` and any
``directory-separators`` immediately following them. The parent of the
root directory is treated as still the root directory (``/../a --> /a``).
6. If the last ``item-name`` is ``..``, remove any trailing
``directory-separator`` (``../ --> ..``).
7. If the path is empty by this stage, add a ``dot`` (normal form of ``./``
is ``.``).
.. _Path Decomposition:
Decomposition
^^^^^^^^^^^^^
.. _GET:
.. _GET_ROOT_NAME:
.. _GET_ROOT_DIRECTORY:
.. _GET_ROOT_PATH:
.. _GET_FILENAME:
.. _GET_EXTENSION:
.. _GET_STEM:
.. _GET_RELATIVE_PART:
.. _GET_PARENT_PATH:
The following forms of the ``GET`` subcommand each retrieve a different
component or group of components from a path. See
`Path Structure And Terminology`_ for the meaning of each path component.
.. code-block:: cmake
cmake_path(GET <path-var> ROOT_NAME <out-var>)
cmake_path(GET <path-var> ROOT_DIRECTORY <out-var>)
cmake_path(GET <path-var> ROOT_PATH <out-var>)
cmake_path(GET <path-var> FILENAME <out-var>)
cmake_path(GET <path-var> EXTENSION [LAST_ONLY] <out-var>)
cmake_path(GET <path-var> STEM [LAST_ONLY] <out-var>)
cmake_path(GET <path-var> RELATIVE_PART <out-var>)
cmake_path(GET <path-var> PARENT_PATH <out-var>)
If a requested component is not present in the path, an empty string will be
stored in ``<out-var>``. For example, only Windows systems have the concept
of a ``root-name``, so when the host machine is non-Windows, the ``ROOT_NAME``
subcommand will always return an empty string.
For ``PARENT_PATH``, if the `HAS_RELATIVE_PART`_ subcommand returns false,
the result is a copy of ``<path-var>``. Note that this implies that a root
directory is considered to have a parent, with that parent being itself.
Where `HAS_RELATIVE_PART`_ returns true, the result will essentially be
``<path-var>`` with one less element.
Root examples
"""""""""""""
.. code-block:: cmake
set(path "c:/a")
cmake_path(GET path ROOT_NAME rootName)
cmake_path(GET path ROOT_DIRECTORY rootDir)
cmake_path(GET path ROOT_PATH rootPath)
message("Root name is \"${rootName}\"")
message("Root directory is \"${rootDir}\"")
message("Root path is \"${rootPath}\"")
::
Root name is "c:"
Root directory is "/"
Root path is "c:/"
Filename examples
"""""""""""""""""
.. code-block:: cmake
set(path "/a/b")
cmake_path(GET path FILENAME filename)
message("First filename is \"${filename}\"")
# Trailing slash means filename is empty
set(path "/a/b/")
cmake_path(GET path FILENAME filename)
message("Second filename is \"${filename}\"")
::
First filename is "b"
Second filename is ""
Extension and stem examples
"""""""""""""""""""""""""""
.. code-block:: cmake
set(path "name.ext1.ext2")
cmake_path(GET path EXTENSION fullExt)
cmake_path(GET path STEM fullStem)
message("Full extension is \"${fullExt}\"")
message("Full stem is \"${fullStem}\"")
# Effect of LAST_ONLY
cmake_path(GET path EXTENSION LAST_ONLY lastExt)
cmake_path(GET path STEM LAST_ONLY lastStem)
message("Last extension is \"${lastExt}\"")
message("Last stem is \"${lastStem}\"")
# Special cases
set(dotPath "/a/.")
set(dotDotPath "/a/..")
set(someMorePath "/a/.some.more")
cmake_path(GET dotPath EXTENSION dotExt)
cmake_path(GET dotPath STEM dotStem)
cmake_path(GET dotDotPath EXTENSION dotDotExt)
cmake_path(GET dotDotPath STEM dotDotStem)
cmake_path(GET dotMorePath EXTENSION someMoreExt)
cmake_path(GET dotMorePath STEM someMoreStem)
message("Dot extension is \"${dotExt}\"")
message("Dot stem is \"${dotStem}\"")
message("Dot-dot extension is \"${dotDotExt}\"")
message("Dot-dot stem is \"${dotDotStem}\"")
message(".some.more extension is \"${someMoreExt}\"")
message(".some.more stem is \"${someMoreStem}\"")
::
Full extension is ".ext1.ext2"
Full stem is "name"
Last extension is ".ext2"
Last stem is "name.ext1"
Dot extension is ""
Dot stem is "."
Dot-dot extension is ""
Dot-dot stem is ".."
.some.more extension is ".more"
.some.more stem is ".some"
Relative part examples
""""""""""""""""""""""
.. code-block:: cmake
set(path "c:/a/b")
cmake_path(GET path RELATIVE_PART result)
message("Relative part is \"${result}\"")
set(path "c/d")
cmake_path(GET path RELATIVE_PART result)
message("Relative part is \"${result}\"")
set(path "/")
cmake_path(GET path RELATIVE_PART result)
message("Relative part is \"${result}\"")
::
Relative part is "a/b"
Relative part is "c/d"
Relative part is ""
Path traversal examples
"""""""""""""""""""""""
.. code-block:: cmake
set(path "c:/a/b")
cmake_path(GET path PARENT_PATH result)
message("Parent path is \"${result}\"")
set(path "c:/")
cmake_path(GET path PARENT_PATH result)
message("Parent path is \"${result}\"")
::
Parent path is "c:/a"
Parent path is "c:/"
.. _Path Query:
Query
^^^^^
Each of the ``GET`` subcommands has a corresponding ``HAS_...``
subcommand which can be used to discover whether a particular path
component is present. See `Path Structure And Terminology`_ for the
meaning of each path component.
.. _HAS_ROOT_NAME:
.. _HAS_ROOT_DIRECTORY:
.. _HAS_ROOT_PATH:
.. _HAS_FILENAME:
.. _HAS_EXTENSION:
.. _HAS_STEM:
.. _HAS_RELATIVE_PART:
.. _HAS_PARENT_PATH:
.. code-block:: cmake
cmake_path(HAS_ROOT_NAME <path-var> <out-var>)
cmake_path(HAS_ROOT_DIRECTORY <path-var> <out-var>)
cmake_path(HAS_ROOT_PATH <path-var> <out-var>)
cmake_path(HAS_FILENAME <path-var> <out-var>)
cmake_path(HAS_EXTENSION <path-var> <out-var>)
cmake_path(HAS_STEM <path-var> <out-var>)
cmake_path(HAS_RELATIVE_PART <path-var> <out-var>)
cmake_path(HAS_PARENT_PATH <path-var> <out-var>)
Each of the above follows the predictable pattern of setting ``<out-var>``
to true if the path has the associated component, or false otherwise.
Note the following special cases:
* For ``HAS_ROOT_PATH``, a true result will only be returned if at least one
of ``root-name`` or ``root-directory`` is non-empty.
* For ``HAS_PARENT_PATH``, the root directory is also considered to have a
parent, which will be itself. The result is true except if the path
consists of just a :ref:`filename <FILENAME_DEF>`.
.. _IS_ABSOLUTE:
.. code-block:: cmake
cmake_path(IS_ABSOLUTE <path-var> <out-var>)
Sets ``<out-var>`` to true if ``<path-var>`` is absolute. An absolute path
is a path that unambiguously identifies the location of a file without
reference to an additional starting location. On Windows, this means the
path must have both a ``root-name`` and a ``root-directory-separator`` to be
considered absolute. On other platforms, just a ``root-directory-separator``
is sufficient. Note that this means on Windows, ``IS_ABSOLUTE`` can be
false while ``HAS_ROOT_DIRECTORY`` can be true.
.. _IS_RELATIVE:
.. code-block:: cmake
cmake_path(IS_RELATIVE <path-var> <out-var>)
This will store the opposite of ``IS_ABSOLUTE`` in ``<out-var>``.
.. _IS_PREFIX:
.. code-block:: cmake
cmake_path(IS_PREFIX <path-var> <input> [NORMALIZE] <out-var>)
Checks if ``<path-var>`` is the prefix of ``<input>``.
When the ``NORMALIZE`` option is specified, ``<path-var>`` and ``<input>``
are :ref:`normalized <Normalization>` before the check.
.. code-block:: cmake
set(path "/a/b/c")
cmake_path(IS_PREFIX path "/a/b/c/d" result) # result = true
cmake_path(IS_PREFIX path "/a/b" result) # result = false
cmake_path(IS_PREFIX path "/x/y/z" result) # result = false
set(path "/a/b")
cmake_path(IS_PREFIX path "/a/c/../b" NORMALIZE result) # result = true
.. _Path COMPARE:
.. _COMPARE:
.. code-block:: cmake
cmake_path(COMPARE <input1> EQUAL <input2> <out-var>)
cmake_path(COMPARE <input1> NOT_EQUAL <input2> <out-var>)
Compares the lexical representations of two paths provided as string literals.
No normalization is performed on either path, except multiple consecutive
directory separators are effectively collapsed into a single separator.
Equality is determined according to the following pseudo-code logic:
::
if(NOT <input1>.root_name() STREQUAL <input2>.root_name())
return FALSE
if(<input1>.has_root_directory() XOR <input2>.has_root_directory())
return FALSE
Return FALSE if a relative portion of <input1> is not lexicographically
equal to the relative portion of <input2>. This comparison is performed path
component-wise. If all of the components compare equal, then return TRUE.
.. note::
Unlike most other ``cmake_path()`` subcommands, the ``COMPARE`` subcommand
takes literal strings as input, not the names of variables.
.. _Path Modification:
Modification
^^^^^^^^^^^^
.. _cmake_path-SET:
.. code-block:: cmake
cmake_path(SET <path-var> [NORMALIZE] <input>)
Assign the ``<input>`` path to ``<path-var>``. If ``<input>`` is a native
path, it is converted into a cmake-style path with forward-slashes
(``/``). On Windows, the long filename marker is taken into account.
When the ``NORMALIZE`` option is specified, the path is :ref:`normalized
<Normalization>` after the conversion.
For example:
.. code-block:: cmake
set(native_path "c:\\a\\b/..\\c")
cmake_path(SET path "${native_path}")
message("CMake path is \"${path}\"")
cmake_path(SET path NORMALIZE "${native_path}")
message("Normalized CMake path is \"${path}\"")
Output::
CMake path is "c:/a/b/../c"
Normalized CMake path is "c:/a/c"
.. _APPEND:
.. code-block:: cmake
cmake_path(APPEND <path-var> [<input>...] [OUTPUT_VARIABLE <out-var>])
Append all the ``<input>`` arguments to the ``<path-var>`` using ``/`` as
the ``directory-separator``. Depending on the ``<input>``, the previous
contents of ``<path-var>`` may be discarded. For each ``<input>`` argument,
the following algorithm (pseudo-code) applies:
::
# <path> is the contents of <path-var>
if(<input>.is_absolute() OR
(<input>.has_root_name() AND
NOT <input>.root_name() STREQUAL <path>.root_name()))
replace <path> with <input>
return()
endif()
if(<input>.has_root_directory())
remove any root-directory and the entire relative path from <path>
elseif(<path>.has_filename() OR
(NOT <path-var>.has_root_directory() OR <path>.is_absolute()))
append directory-separator to <path>
endif()
append <input> omitting any root-name to <path>
.. _APPEND_STRING:
.. code-block:: cmake
cmake_path(APPEND_STRING <path-var> [<input>...] [OUTPUT_VARIABLE <out-var>])
Append all the ``<input>`` arguments to the ``<path-var>`` without adding any
``directory-separator``.
.. _REMOVE_FILENAME:
.. code-block:: cmake
cmake_path(REMOVE_FILENAME <path-var> [OUTPUT_VARIABLE <out-var>])
Removes the :ref:`filename <FILENAME_DEF>` component (as returned by
:ref:`GET ... FILENAME <GET_FILENAME>`) from ``<path-var>``. After removal,
any trailing ``directory-separator`` is left alone, if present.
If ``OUTPUT_VARIABLE`` is not given, then after this function returns,
`HAS_FILENAME`_ returns false for ``<path-var>``.
For example:
.. code-block:: cmake
set(path "/a/b")
cmake_path(REMOVE_FILENAME path)
message("First path is \"${path}\"")
# filename is now already empty, the following removes nothing
cmake_path(REMOVE_FILENAME path)
message("Second path is \"${path}\"")
Output::
First path is "/a/"
Second path is "/a/"
.. _REPLACE_FILENAME:
.. code-block:: cmake
cmake_path(REPLACE_FILENAME <path-var> <input> [OUTPUT_VARIABLE <out-var>])
Replaces the :ref:`filename <FILENAME_DEF>` component from ``<path-var>``
with ``<input>``. If ``<path-var>`` has no filename component (i.e.
`HAS_FILENAME`_ returns false), the path is unchanged. The operation is
equivalent to the following:
.. code-block:: cmake
cmake_path(HAS_FILENAME path has_filename)
if(has_filename)
cmake_path(REMOVE_FILENAME path)
cmake_path(APPEND path input);
endif()
.. _REMOVE_EXTENSION:
.. code-block:: cmake
cmake_path(REMOVE_EXTENSION <path-var> [LAST_ONLY]
[OUTPUT_VARIABLE <out-var>])
Removes the :ref:`extension <EXTENSION_DEF>`, if any, from ``<path-var>``.
.. _REPLACE_EXTENSION:
.. code-block:: cmake
cmake_path(REPLACE_EXTENSION <path-var> [LAST_ONLY] <input>
[OUTPUT_VARIABLE <out-var>])
Replaces the :ref:`extension <EXTENSION_DEF>` with ``<input>``. Its effect
is equivalent to the following:
.. code-block:: cmake
cmake_path(REMOVE_EXTENSION path)
if(NOT "input" MATCHES "^\\.")
cmake_path(APPEND_STRING path ".")
endif()
cmake_path(APPEND_STRING path "input")
.. _Path Generation:
Generation
^^^^^^^^^^
.. _NORMAL_PATH:
.. code-block:: cmake
cmake_path(NORMAL_PATH <path-var> [OUTPUT_VARIABLE <out-var>])
Normalize ``<path-var>`` according the steps described in :ref:`Normalization`.
.. _cmake_path-RELATIVE_PATH:
.. _RELATIVE_PATH:
.. code-block:: cmake
cmake_path(RELATIVE_PATH <path-var> [BASE_DIRECTORY <input>]
[OUTPUT_VARIABLE <out-var>])
Modifies ``<path-var>`` to make it relative to the ``BASE_DIRECTORY`` argument.
If ``BASE_DIRECTORY`` is not specified, the default base directory will be
:variable:`CMAKE_CURRENT_SOURCE_DIR`.
For reference, the algorithm used to compute the relative path is the same
as that used by C++
`std::filesystem::path::lexically_relative
<https://en.cppreference.com/w/cpp/filesystem/path/lexically_normal>`_.
.. _ABSOLUTE_PATH:
.. code-block:: cmake
cmake_path(ABSOLUTE_PATH <path-var> [BASE_DIRECTORY <input>] [NORMALIZE]
[OUTPUT_VARIABLE <out-var>])
If ``<path-var>`` is a relative path (`IS_RELATIVE`_ is true), it is evaluated
relative to the given base directory specified by ``BASE_DIRECTORY`` option.
If ``BASE_DIRECTORY`` is not specified, the default base directory will be
:variable:`CMAKE_CURRENT_SOURCE_DIR`.
When the ``NORMALIZE`` option is specified, the path is :ref:`normalized
<Normalization>` after the path computation.
Because ``cmake_path()`` does not access the filesystem, symbolic links are
not resolved and any leading tilde is not expanded. To compute a real path
with symbolic links resolved and leading tildes expanded, use the
:command:`file(REAL_PATH)` command instead.
Native Conversion
^^^^^^^^^^^^^^^^^
For commands in this section, *native* refers to the host platform, not the
target platform when cross-compiling.
.. _cmake_path-NATIVE_PATH:
.. _NATIVE_PATH:
.. code-block:: cmake
cmake_path(NATIVE_PATH <path-var> [NORMALIZE] <out-var>)
Converts a cmake-style ``<path-var>`` into a native path with
platform-specific slashes (``\`` on Windows hosts and ``/`` elsewhere).
When the ``NORMALIZE`` option is specified, the path is :ref:`normalized
<Normalization>` before the conversion.
.. _CONVERT:
.. _cmake_path-TO_CMAKE_PATH_LIST:
.. _TO_CMAKE_PATH_LIST:
.. code-block:: cmake
cmake_path(CONVERT <input> TO_CMAKE_PATH_LIST <out-var> [NORMALIZE])
Converts a native ``<input>`` path into a cmake-style path with forward
slashes (``/``). On Windows hosts, the long filename marker is taken into
account. The input can be a single path or a system search path like
``$ENV{PATH}``. A search path will be converted to a cmake-style list
separated by ``;`` characters (on non-Windows platforms, this essentially
means ``:`` separators are replaced with ``;``). The result of the
conversion is stored in the ``<out-var>`` variable.
When the ``NORMALIZE`` option is specified, the path is :ref:`normalized
<Normalization>` before the conversion.
.. note::
Unlike most other ``cmake_path()`` subcommands, the ``CONVERT`` subcommand
takes a literal string as input, not the name of a variable.
.. _cmake_path-TO_NATIVE_PATH_LIST:
.. _TO_NATIVE_PATH_LIST:
.. code-block:: cmake
cmake_path(CONVERT <input> TO_NATIVE_PATH_LIST <out-var> [NORMALIZE])
Converts a cmake-style ``<input>`` path into a native path with
platform-specific slashes (``\`` on Windows hosts and ``/`` elsewhere).
The input can be a single path or a cmake-style list. A list will be
converted into a native search path (``;``-separated on Windows,
``:``-separated on other platforms). The result of the conversion is
stored in the ``<out-var>`` variable.
When the ``NORMALIZE`` option is specified, the path is :ref:`normalized
<Normalization>` before the conversion.
.. note::
Unlike most other ``cmake_path()`` subcommands, the ``CONVERT`` subcommand
takes a literal string as input, not the name of a variable.
For example:
.. code-block:: cmake
set(paths "/a/b/c" "/x/y/z")
cmake_path(CONVERT "${paths}" TO_NATIVE_PATH_LIST native_paths)
message("Native path list is \"${native_paths}\"")
Output on Windows::
Native path list is "\a\b\c;\x\y\z"
Output on all other platforms::
Native path list is "/a/b/c:/x/y/z"
Hashing
^^^^^^^
.. _HASH:
.. code-block:: cmake
cmake_path(HASH <path-var> <out-var>)
Compute a hash value of ``<path-var>`` such that for two paths ``p1`` and
``p2`` that compare equal (:ref:`COMPARE ... EQUAL <COMPARE>`), the hash
value of ``p1`` is equal to the hash value of ``p2``. The path is always
:ref:`normalized <Normalization>` before the hash is computed.

159
cmake/share/cmake-3.30/Help/command/cmake_policy.rst Normal file
View File

@ -0,0 +1,159 @@
cmake_policy
------------
Manage CMake Policy settings. See the :manual:`cmake-policies(7)`
manual for defined policies.
As CMake evolves it is sometimes necessary to change existing behavior
in order to fix bugs or improve implementations of existing features.
The CMake Policy mechanism is designed to help keep existing projects
building as new versions of CMake introduce changes in behavior. Each
new policy (behavioral change) is given an identifier of the form
``CMP<NNNN>`` where ``<NNNN>`` is an integer index. Documentation
associated with each policy describes the ``OLD`` and ``NEW`` behavior
and the reason the policy was introduced. Projects may set each policy
to select the desired behavior. When CMake needs to know which behavior
to use it checks for a setting specified by the project. If no
setting is available the ``OLD`` behavior is assumed and a warning is
produced requesting that the policy be set.
Setting Policies by CMake Version
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
The ``cmake_policy`` command is used to set policies to ``OLD`` or ``NEW``
behavior. While setting policies individually is supported, we
encourage projects to set policies based on CMake versions:
.. signature:: cmake_policy(VERSION <min>[...<max>])
:target: VERSION
.. versionadded:: 3.12
The optional ``<max>`` version.
``<min>`` and the optional ``<max>`` are each CMake versions of the form
``major.minor[.patch[.tweak]]``, and the ``...`` is literal. The ``<min>``
version must be at least ``2.4`` and at most the running version of CMake.
The ``<max>`` version, if specified, must be at least the ``<min>`` version
but may exceed the running version of CMake. If the running version of
CMake is older than 3.12, the extra ``...`` dots will be seen as version
component separators, resulting in the ``...<max>`` part being ignored and
preserving the pre-3.12 behavior of basing policies on ``<min>``.
This specifies that the current CMake code is written for the given
range of CMake versions. All policies known to the running version of CMake
and introduced in the ``<min>`` (or ``<max>``, if specified) version
or earlier will be set to use ``NEW`` behavior. All policies
introduced in later versions will be unset (unless the
:variable:`CMAKE_POLICY_DEFAULT_CMP<NNNN>` variable sets a default).
This effectively requests behavior preferred as of a given CMake
version and tells newer CMake versions to warn about their new policies.
Note that the :command:`cmake_minimum_required(VERSION)`
command implicitly calls ``cmake_policy(VERSION)`` too.
.. include:: DEPRECATED_POLICY_VERSIONS.txt
Setting Policies Explicitly
^^^^^^^^^^^^^^^^^^^^^^^^^^^
.. signature:: cmake_policy(SET CMP<NNNN> NEW|OLD)
:target: SET
Tell CMake to use the ``OLD`` or ``NEW`` behavior for a given policy.
Projects depending on the old behavior of a given policy may silence a
policy warning by setting the policy state to ``OLD``. Alternatively
one may fix the project to work with the new behavior and set the
policy state to ``NEW``.
.. include:: ../policy/DEPRECATED.txt
Checking Policy Settings
^^^^^^^^^^^^^^^^^^^^^^^^
.. signature:: cmake_policy(GET CMP<NNNN> <variable>)
:target: GET
Check whether a given policy is set to ``OLD`` or ``NEW`` behavior.
The output ``<variable>`` value will be ``OLD`` or ``NEW`` if the
policy is set, and empty otherwise.
CMake Policy Stack
^^^^^^^^^^^^^^^^^^
CMake keeps policy settings on a stack, so changes made by the
``cmake_policy`` command affect only the top of the stack. A new entry on
the policy stack is managed automatically for each subdirectory to
protect its parents and siblings. CMake also manages a new entry for
scripts loaded by :command:`include` and :command:`find_package` commands
except when invoked with the ``NO_POLICY_SCOPE`` option
(see also policy :policy:`CMP0011`).
The ``cmake_policy`` command provides an interface to manage custom
entries on the policy stack:
.. signature:: cmake_policy(PUSH)
:target: PUSH
Create a new entry on the policy stack.
.. signature:: cmake_policy(POP)
:target: POP
Remove the last policy stack entry created with ``cmake_policy(PUSH)``.
Each ``PUSH`` must have a matching ``POP`` to erase any changes.
This is useful to make temporary changes to policy settings.
Calls to the :command:`cmake_minimum_required(VERSION)`,
:command:`cmake_policy(VERSION)`, or :command:`cmake_policy(SET)` commands
influence only the current top of the policy stack.
.. versionadded:: 3.25
The :command:`block(SCOPE_FOR POLICIES)` command offers a more flexible
and more secure way to manage the policy stack. The pop action is done
automatically when leaving the block scope, so there is no need to
precede each :command:`return` with a call to :command:`cmake_policy(POP)`.
.. code-block:: cmake
# stack management with cmake_policy()
function(my_func)
cmake_policy(PUSH)
cmake_policy(SET ...)
if (<cond1>)
...
cmake_policy(POP)
return()
elseif(<cond2>)
...
cmake_policy(POP)
return()
endif()
...
cmake_policy(POP)
endfunction()
# stack management with block()/endblock()
function(my_func)
block(SCOPE_FOR POLICIES)
cmake_policy(SET ...)
if (<cond1>)
...
return()
elseif(<cond2>)
...
return()
endif()
...
endblock()
endfunction()
Commands created by the :command:`function` and :command:`macro`
commands record policy settings when they are created and
use the pre-record policies when they are invoked. If the function or
macro implementation sets policies, the changes automatically
propagate up through callers until they reach the closest nested
policy stack entry.
See Also
^^^^^^^^
* :command:`cmake_minimum_required`

203
cmake/share/cmake-3.30/Help/command/configure_file.rst Normal file
View File

@ -0,0 +1,203 @@
configure_file
--------------
.. only:: html
.. contents::
Copy a file to another location and modify its contents.
.. code-block:: cmake
configure_file(<input> <output>
[NO_SOURCE_PERMISSIONS | USE_SOURCE_PERMISSIONS |
FILE_PERMISSIONS <permissions>...]
[COPYONLY] [ESCAPE_QUOTES] [@ONLY]
[NEWLINE_STYLE [UNIX|DOS|WIN32|LF|CRLF] ])
Copies an ``<input>`` file to an ``<output>`` file while performing
`transformations`_ of the input file content.
If the input file is modified the build system will re-run CMake to
re-configure the file and generate the build system again.
The generated file is modified and its timestamp updated on subsequent
cmake runs only if its content is changed.
Options
^^^^^^^
The options are:
``<input>``
Path to the input file. A relative path is treated with respect to
the value of :variable:`CMAKE_CURRENT_SOURCE_DIR`. The input path
must be a file, not a directory.
``<output>``
Path to the output file or directory. A relative path is treated
with respect to the value of :variable:`CMAKE_CURRENT_BINARY_DIR`.
If the path names an existing directory the output file is placed
in that directory with the same file name as the input file.
If the path contains non-existent directories, they are created.
``NO_SOURCE_PERMISSIONS``
.. versionadded:: 3.19
Do not transfer the permissions of the input file to the output file.
The copied file permissions default to the standard 644 value
(-rw-r--r--).
``USE_SOURCE_PERMISSIONS``
.. versionadded:: 3.20
Transfer the permissions of the input file to the output file.
This is already the default behavior if none of the three permissions-related
keywords are given (``NO_SOURCE_PERMISSIONS``, ``USE_SOURCE_PERMISSIONS``
or ``FILE_PERMISSIONS``). The ``USE_SOURCE_PERMISSIONS`` keyword mostly
serves as a way of making the intended behavior clearer at the call site.
``FILE_PERMISSIONS <permissions>...``
.. versionadded:: 3.20
Ignore the input file's permissions and use the specified ``<permissions>``
for the output file instead.
``COPYONLY``
Copy the file without replacing any variable references or other
content. This option may not be used with ``NEWLINE_STYLE``.
``ESCAPE_QUOTES``
Escape any substituted quotes with backslashes (C-style).
``@ONLY``
Restrict variable replacement to references of the form ``@VAR@``.
This is useful for configuring scripts that use ``${VAR}`` syntax.
``NEWLINE_STYLE <style>``
Specify the newline style for the output file. Specify
``UNIX`` or ``LF`` for ``\n`` newlines, or specify
``DOS``, ``WIN32``, or ``CRLF`` for ``\r\n`` newlines.
This option may not be used with ``COPYONLY``.
Transformations
^^^^^^^^^^^^^^^
:ref:`Variables <CMake Language Variables>` referenced in the input
file content as ``@VAR@``, ``${VAR}``, ``$CACHE{VAR}``, and
:ref:`environment variables <CMake Language Environment Variables>`
referenced as ``$ENV{VAR}``, will each be replaced with the current value
of the variable, or the empty string if the variable is not defined.
Furthermore, input lines of the form
.. code-block:: c
#cmakedefine VAR ...
will be replaced with either
.. code-block:: c
#define VAR ...
or
.. code-block:: c
/* #undef VAR */
depending on whether ``VAR`` is set in CMake to any value not considered
a false constant by the :command:`if` command. The "..." content on the
line after the variable name, if any, is processed as above.
Unlike lines of the form ``#cmakedefine VAR ...``, in lines of the form
``#cmakedefine01 VAR``, ``VAR`` itself will expand to ``VAR 0`` or ``VAR 1``
rather than being assigned the value ``...``. Therefore, input lines of the form
.. code-block:: c
#cmakedefine01 VAR
will be replaced with either
.. code-block:: c
#define VAR 0
or
.. code-block:: c
#define VAR 1
Input lines of the form ``#cmakedefine01 VAR ...`` will expand
as ``#cmakedefine01 VAR ... 0`` or ``#cmakedefine01 VAR ... 1``,
which may lead to undefined behavior.
.. versionadded:: 3.10
The result lines (with the exception of the ``#undef`` comments) can be
indented using spaces and/or tabs between the ``#`` character
and the ``cmakedefine`` or ``cmakedefine01`` words. This whitespace
indentation will be preserved in the output lines:
.. code-block:: c
# cmakedefine VAR
# cmakedefine01 VAR
will be replaced, if ``VAR`` is defined, with
.. code-block:: c
# define VAR
# define VAR 1
Example
^^^^^^^
Consider a source tree containing a ``foo.h.in`` file:
.. code-block:: c
#cmakedefine FOO_ENABLE
#cmakedefine FOO_STRING "@FOO_STRING@"
An adjacent ``CMakeLists.txt`` may use ``configure_file`` to
configure the header:
.. code-block:: cmake
option(FOO_ENABLE "Enable Foo" ON)
if(FOO_ENABLE)
set(FOO_STRING "foo")
endif()
configure_file(foo.h.in foo.h @ONLY)
This creates a ``foo.h`` in the build directory corresponding to
this source directory. If the ``FOO_ENABLE`` option is on, the
configured file will contain:
.. code-block:: c
#define FOO_ENABLE
#define FOO_STRING "foo"
Otherwise it will contain:
.. code-block:: c
/* #undef FOO_ENABLE */
/* #undef FOO_STRING */
One may then use the :command:`target_include_directories` command to
specify the output directory as an include directory:
.. code-block:: cmake
target_include_directories(<target> [SYSTEM] <INTERFACE|PUBLIC|PRIVATE> "${CMAKE_CURRENT_BINARY_DIR}")
so that sources may include the header as ``#include <foo.h>``.
See Also
^^^^^^^^
* :command:`file(GENERATE)`

16
cmake/share/cmake-3.30/Help/command/continue.rst Normal file
View File

@ -0,0 +1,16 @@
continue
--------
.. versionadded:: 3.2
Continue to the top of enclosing foreach or while loop.
.. code-block:: cmake
continue()
The ``continue()`` command allows a cmake script to abort the rest of the
current iteration of a :command:`foreach` or :command:`while` loop, and start
at the top of the next iteration.
See also the :command:`break` command.

62
cmake/share/cmake-3.30/Help/command/create_test_sourcelist.rst Normal file
View File

@ -0,0 +1,62 @@
create_test_sourcelist
----------------------
Create a test driver program that links together many small tests into a
single executable. This is useful when building static executables with
large libraries to shrink the total required size.
.. signature::
create_test_sourcelist(<sourceListName> <driverName> <test>... <options>...)
:target: original
Generate a test driver source file from a list of individual test sources
and provide a combined list of sources that can be built as an executable.
The options are:
``<sourceListName>``
The name of a variable in which to store the list of source files needed
to build the test driver. The list will contain the ``<test>...`` sources
and the generated ``<driverName>`` source.
.. versionchanged:: 3.29
The test driver source is listed by absolute path in the build tree.
Previously it was listed only as ``<driverName>``.
``<driverName>``
Name of the test driver source file to be generated into the build tree.
The source file will contain a ``main()`` program entry point that
dispatches to whatever test is named on the command line.
``<test>...``
Test source files to be added to the driver binary. Each test source
file must have a function in it that is the same name as the file with the
extension removed. For example, a ``foo.cxx`` test source might contain:
.. code-block:: c++
int foo(int argc, char** argv)
``EXTRA_INCLUDE <header>``
Specify a header file to ``#include`` in the generated test driver source.
``FUNCTION <function>``
Specify a function to be called with pointers to ``argc`` and ``argv``.
The function may be provided in the ``EXTRA_INCLUDE`` header:
.. code-block:: c++
void function(int* pargc, char*** pargv)
This can be used to add extra command line processing to each test.
Additionally, some CMake variables affect test driver generation:
.. variable:: CMAKE_TESTDRIVER_BEFORE_TESTMAIN
Code to be placed directly before calling each test's function.
.. variable:: CMAKE_TESTDRIVER_AFTER_TESTMAIN
Code to be placed directly after the call to each test's function.

93
cmake/share/cmake-3.30/Help/command/ctest_build.rst Normal file
View File

@ -0,0 +1,93 @@
ctest_build
-----------
Perform the :ref:`CTest Build Step` as a :ref:`Dashboard Client`.
.. code-block:: cmake
ctest_build([BUILD <build-dir>] [APPEND]
[CONFIGURATION <config>]
[PARALLEL_LEVEL <parallel>]
[FLAGS <flags>]
[PROJECT_NAME <project-name>]
[TARGET <target-name>]
[NUMBER_ERRORS <num-err-var>]
[NUMBER_WARNINGS <num-warn-var>]
[RETURN_VALUE <result-var>]
[CAPTURE_CMAKE_ERROR <result-var>]
)
Build the project and store results in ``Build.xml``
for submission with the :command:`ctest_submit` command.
The :variable:`CTEST_BUILD_COMMAND` variable may be set to explicitly
specify the build command line. Otherwise the build command line is
computed automatically based on the options given.
The options are:
``BUILD <build-dir>``
Specify the top-level build directory. If not given, the
:variable:`CTEST_BINARY_DIRECTORY` variable is used.
``APPEND``
Mark ``Build.xml`` for append to results previously submitted to a
dashboard server since the last :command:`ctest_start` call.
Append semantics are defined by the dashboard server in use.
This does *not* cause results to be appended to a ``.xml`` file
produced by a previous call to this command.
``CONFIGURATION <config>``
Specify the build configuration (e.g. ``Debug``). If not
specified the ``CTEST_BUILD_CONFIGURATION`` variable will be checked.
Otherwise the :option:`-C \<cfg\> <ctest -C>` option given to the
:manual:`ctest(1)` command will be used, if any.
``PARALLEL_LEVEL <parallel>``
.. versionadded:: 3.21
Specify the parallel level of the underlying build system. If not
specified, the :envvar:`CMAKE_BUILD_PARALLEL_LEVEL` environment
variable will be checked.
``FLAGS <flags>``
Pass additional arguments to the underlying build command.
If not specified the ``CTEST_BUILD_FLAGS`` variable will be checked.
This can, e.g., be used to trigger a parallel build using the
``-j`` option of ``make``. See the :module:`ProcessorCount` module
for an example.
``PROJECT_NAME <project-name>``
Ignored since CMake 3.0.
.. versionchanged:: 3.14
This value is no longer required.
``TARGET <target-name>``
Specify the name of a target to build. If not specified the
``CTEST_BUILD_TARGET`` variable will be checked. Otherwise the
default target will be built. This is the "all" target
(called ``ALL_BUILD`` in :ref:`Visual Studio Generators`).
``NUMBER_ERRORS <num-err-var>``
Store the number of build errors detected in the given variable.
``NUMBER_WARNINGS <num-warn-var>``
Store the number of build warnings detected in the given variable.
``RETURN_VALUE <result-var>``
Store the return value of the native build tool in the given variable.
``CAPTURE_CMAKE_ERROR <result-var>``
.. versionadded:: 3.7
Store in the ``<result-var>`` variable -1 if there are any errors running
the command and prevent ctest from returning non-zero if an error occurs.
``QUIET``
.. versionadded:: 3.3
Suppress any CTest-specific non-error output that would have been
printed to the console otherwise. The summary of warnings / errors,
as well as the output from the native build tool is unaffected by
this option.

50
cmake/share/cmake-3.30/Help/command/ctest_configure.rst Normal file
View File

@ -0,0 +1,50 @@
ctest_configure
---------------
Perform the :ref:`CTest Configure Step` as a :ref:`Dashboard Client`.
.. code-block:: cmake
ctest_configure([BUILD <build-dir>] [SOURCE <source-dir>] [APPEND]
[OPTIONS <options>] [RETURN_VALUE <result-var>] [QUIET]
[CAPTURE_CMAKE_ERROR <result-var>])
Configure the project build tree and record results in ``Configure.xml``
for submission with the :command:`ctest_submit` command.
The options are:
``BUILD <build-dir>``
Specify the top-level build directory. If not given, the
:variable:`CTEST_BINARY_DIRECTORY` variable is used.
``SOURCE <source-dir>``
Specify the source directory. If not given, the
:variable:`CTEST_SOURCE_DIRECTORY` variable is used.
``APPEND``
Mark ``Configure.xml`` for append to results previously submitted to a
dashboard server since the last :command:`ctest_start` call.
Append semantics are defined by the dashboard server in use.
This does *not* cause results to be appended to a ``.xml`` file
produced by a previous call to this command.
``OPTIONS <options>``
Specify command-line arguments to pass to the configuration tool.
``RETURN_VALUE <result-var>``
Store in the ``<result-var>`` variable the return value of the native
configuration tool.
``CAPTURE_CMAKE_ERROR <result-var>``
.. versionadded:: 3.7
Store in the ``<result-var>`` variable -1 if there are any errors running
the command and prevent ctest from returning non-zero if an error occurs.
``QUIET``
.. versionadded:: 3.3
Suppress any CTest-specific non-error messages that would have
otherwise been printed to the console. Output from the underlying
configure command is not affected.

50
cmake/share/cmake-3.30/Help/command/ctest_coverage.rst Normal file
View File

@ -0,0 +1,50 @@
ctest_coverage
--------------
Perform the :ref:`CTest Coverage Step` as a :ref:`Dashboard Client`.
.. code-block:: cmake
ctest_coverage([BUILD <build-dir>] [APPEND]
[LABELS <label>...]
[RETURN_VALUE <result-var>]
[CAPTURE_CMAKE_ERROR <result-var>]
[QUIET]
)
Collect coverage tool results and stores them in ``Coverage.xml``
for submission with the :command:`ctest_submit` command.
The options are:
``BUILD <build-dir>``
Specify the top-level build directory. If not given, the
:variable:`CTEST_BINARY_DIRECTORY` variable is used.
``APPEND``
Mark ``Coverage.xml`` for append to results previously submitted to a
dashboard server since the last :command:`ctest_start` call.
Append semantics are defined by the dashboard server in use.
This does *not* cause results to be appended to a ``.xml`` file
produced by a previous call to this command.
``LABELS``
Filter the coverage report to include only source files labeled
with at least one of the labels specified.
``RETURN_VALUE <result-var>``
Store in the ``<result-var>`` variable ``0`` if coverage tools
ran without error and non-zero otherwise.
``CAPTURE_CMAKE_ERROR <result-var>``
.. versionadded:: 3.7
Store in the ``<result-var>`` variable -1 if there are any errors running
the command and prevent ctest from returning non-zero if an error occurs.
``QUIET``
.. versionadded:: 3.3
Suppress any CTest-specific non-error output that would have been
printed to the console otherwise. The summary indicating how many
lines of code were covered is unaffected by this option.

12
cmake/share/cmake-3.30/Help/command/ctest_empty_binary_directory.rst Normal file
View File

@ -0,0 +1,12 @@
ctest_empty_binary_directory
----------------------------
empties the binary directory
.. code-block:: cmake
ctest_empty_binary_directory(<directory>)
Removes a binary directory. This command will perform some checks
prior to deleting the directory in an attempt to avoid malicious or
accidental directory deletion.

45
cmake/share/cmake-3.30/Help/command/ctest_memcheck.rst Normal file
View File

@ -0,0 +1,45 @@
ctest_memcheck
--------------
Perform the :ref:`CTest MemCheck Step` as a :ref:`Dashboard Client`.
.. code-block:: cmake
ctest_memcheck([BUILD <build-dir>] [APPEND]
[START <start-number>]
[END <end-number>]
[STRIDE <stride-number>]
[EXCLUDE <exclude-regex>]
[INCLUDE <include-regex>]
[EXCLUDE_LABEL <label-exclude-regex>]
[INCLUDE_LABEL <label-include-regex>]
[EXCLUDE_FIXTURE <regex>]
[EXCLUDE_FIXTURE_SETUP <regex>]
[EXCLUDE_FIXTURE_CLEANUP <regex>]
[PARALLEL_LEVEL <level>]
[RESOURCE_SPEC_FILE <file>]
[TEST_LOAD <threshold>]
[SCHEDULE_RANDOM <ON|OFF>]
[STOP_ON_FAILURE]
[STOP_TIME <time-of-day>]
[RETURN_VALUE <result-var>]
[CAPTURE_CMAKE_ERROR <result-var>]
[REPEAT <mode>:<n>]
[OUTPUT_JUNIT <file>]
[DEFECT_COUNT <defect-count-var>]
[QUIET]
)
Run tests with a dynamic analysis tool and store results in
``MemCheck.xml`` for submission with the :command:`ctest_submit`
command.
Most options are the same as those for the :command:`ctest_test` command.
The options unique to this command are:
``DEFECT_COUNT <defect-count-var>``
.. versionadded:: 3.8
Store in the ``<defect-count-var>`` the number of defects found.

14
cmake/share/cmake-3.30/Help/command/ctest_read_custom_files.rst Normal file
View File

@ -0,0 +1,14 @@
ctest_read_custom_files
-----------------------
read CTestCustom files.
.. code-block:: cmake
ctest_read_custom_files(<directory>...)
Read all the CTestCustom.ctest or CTestCustom.cmake files from the
given directory.
By default, invoking :manual:`ctest(1)` without a script will read custom
files from the binary directory.

15
cmake/share/cmake-3.30/Help/command/ctest_run_script.rst Normal file
View File

@ -0,0 +1,15 @@
ctest_run_script
----------------
runs a :option:`ctest -S` script
.. code-block:: cmake
ctest_run_script([NEW_PROCESS] script_file_name script_file_name1
script_file_name2 ... [RETURN_VALUE var])
Runs a script or scripts much like if it was run from :option:`ctest -S`.
If no argument is provided then the current script is run using the current
settings of the variables. If ``NEW_PROCESS`` is specified then each
script will be run in a separate process.If ``RETURN_VALUE`` is specified
the return value of the last script run will be put into ``var``.

16
cmake/share/cmake-3.30/Help/command/ctest_sleep.rst Normal file
View File

@ -0,0 +1,16 @@
ctest_sleep
-----------
sleeps for some amount of time
.. code-block:: cmake
ctest_sleep(<seconds>)
Sleep for given number of seconds.
.. code-block:: cmake
ctest_sleep(<time1> <duration> <time2>)
Sleep for t=(time1 + duration - time2) seconds if t > 0.

88
cmake/share/cmake-3.30/Help/command/ctest_start.rst Normal file
View File

@ -0,0 +1,88 @@
ctest_start
-----------
Starts the testing for a given model
.. code-block:: cmake
ctest_start(<model> [<source> [<binary>]] [GROUP <group>] [QUIET])
ctest_start([<model> [<source> [<binary>]]] [GROUP <group>] APPEND [QUIET])
Starts the testing for a given model. The command should be called
after the binary directory is initialized.
The parameters are as follows:
``<model>``
Set the dashboard model. Must be one of ``Experimental``, ``Continuous``, or
``Nightly``. This parameter is required unless ``APPEND`` is specified.
``<source>``
Set the source directory. If not specified, the value of
:variable:`CTEST_SOURCE_DIRECTORY` is used instead.
``<binary>``
Set the binary directory. If not specified, the value of
:variable:`CTEST_BINARY_DIRECTORY` is used instead.
``GROUP <group>``
If ``GROUP`` is used, the submissions will go to the specified group on the
CDash server. If no ``GROUP`` is specified, the name of the model is used by
default.
.. versionchanged:: 3.16
This replaces the deprecated option ``TRACK``. Despite the name
change its behavior is unchanged.
``APPEND``
If ``APPEND`` is used, the existing ``TAG`` is used rather than creating a new
one based on the current time stamp. If you use ``APPEND``, you can omit the
``<model>`` and ``GROUP <group>`` parameters, because they will be read from
the generated ``TAG`` file. For example:
.. code-block:: cmake
ctest_start(Experimental GROUP GroupExperimental)
Later, in another :option:`ctest -S` script:
.. code-block:: cmake
ctest_start(APPEND)
When the second script runs ``ctest_start(APPEND)``, it will read the
``Experimental`` model and ``GroupExperimental`` group from the ``TAG`` file
generated by the first ``ctest_start()`` command. Please note that if you
call ``ctest_start(APPEND)`` and specify a different model or group than
in the first ``ctest_start()`` command, a warning will be issued, and the
new model and group will be used.
``QUIET``
.. versionadded:: 3.3
If ``QUIET`` is used, CTest will suppress any non-error messages that it
otherwise would have printed to the console.
The parameters for ``ctest_start()`` can be issued in any order, with the
exception that ``<model>``, ``<source>``, and ``<binary>`` have to appear
in that order with respect to each other. The following are all valid and
equivalent:
.. code-block:: cmake
ctest_start(Experimental path/to/source path/to/binary GROUP SomeGroup QUIET APPEND)
ctest_start(GROUP SomeGroup Experimental QUIET path/to/source APPEND path/to/binary)
ctest_start(APPEND QUIET Experimental path/to/source GROUP SomeGroup path/to/binary)
However, for the sake of readability, it is recommended that you order your
parameters in the order listed at the top of this page.
If the :variable:`CTEST_CHECKOUT_COMMAND` variable (or the
:variable:`CTEST_CVS_CHECKOUT` variable) is set, its content is treated as
command-line. The command is invoked with the current working directory set
to the parent of the source directory, even if the source directory already
exists. This can be used to create the source tree from a version control
repository.

131
cmake/share/cmake-3.30/Help/command/ctest_submit.rst Normal file
View File

@ -0,0 +1,131 @@
ctest_submit
------------
Perform the :ref:`CTest Submit Step` as a :ref:`Dashboard Client`.
.. code-block:: cmake
ctest_submit([PARTS <part>...] [FILES <file>...]
[SUBMIT_URL <url>]
[BUILD_ID <result-var>]
[HTTPHEADER <header>]
[RETRY_COUNT <count>]
[RETRY_DELAY <delay>]
[RETURN_VALUE <result-var>]
[CAPTURE_CMAKE_ERROR <result-var>]
[QUIET]
)
Submit results to a dashboard server.
By default all available parts are submitted.
The options are:
``PARTS <part>...``
Specify a subset of parts to submit. Valid part names are::
Start = nothing
Update = ctest_update results, in Update.xml
Configure = ctest_configure results, in Configure.xml
Build = ctest_build results, in Build.xml
Test = ctest_test results, in Test.xml
Coverage = ctest_coverage results, in Coverage.xml
MemCheck = ctest_memcheck results, in DynamicAnalysis.xml and
DynamicAnalysis-Test.xml
Notes = Files listed by CTEST_NOTES_FILES, in Notes.xml
ExtraFiles = Files listed by CTEST_EXTRA_SUBMIT_FILES
Upload = Files prepared for upload by ctest_upload(), in Upload.xml
Submit = nothing
Done = Build is complete, in Done.xml
``FILES <file>...``
Specify an explicit list of specific files to be submitted.
Each individual file must exist at the time of the call.
``SUBMIT_URL <url>``
.. versionadded:: 3.14
The ``http`` or ``https`` URL of the dashboard server to send the submission
to. If not given, the :variable:`CTEST_SUBMIT_URL` variable is used.
``BUILD_ID <result-var>``
.. versionadded:: 3.15
Store in the ``<result-var>`` variable the ID assigned to this build by
CDash.
``HTTPHEADER <HTTP-header>``
.. versionadded:: 3.9
Specify HTTP header to be included in the request to CDash during submission.
For example, CDash can be configured to only accept submissions from
authenticated clients. In this case, you should provide a bearer token in your
header:
.. code-block:: cmake
ctest_submit(HTTPHEADER "Authorization: Bearer <auth-token>")
This suboption can be repeated several times for multiple headers.
``RETRY_COUNT <count>``
Specify how many times to retry a timed-out submission.
``RETRY_DELAY <delay>``
Specify how long (in seconds) to wait after a timed-out submission
before attempting to re-submit.
``RETURN_VALUE <result-var>``
Store in the ``<result-var>`` variable ``0`` for success and
non-zero on failure.
``CAPTURE_CMAKE_ERROR <result-var>``
.. versionadded:: 3.13
Store in the ``<result-var>`` variable -1 if there are any errors running
the command and prevent ctest from returning non-zero if an error occurs.
``QUIET``
.. versionadded:: 3.3
Suppress all non-error messages that would have otherwise been
printed to the console.
Submit to CDash Upload API
^^^^^^^^^^^^^^^^^^^^^^^^^^
.. versionadded:: 3.2
.. code-block:: cmake
ctest_submit(CDASH_UPLOAD <file> [CDASH_UPLOAD_TYPE <type>]
[SUBMIT_URL <url>]
[BUILD_ID <result-var>]
[HTTPHEADER <header>]
[RETRY_COUNT <count>]
[RETRY_DELAY <delay>]
[RETURN_VALUE <result-var>]
[QUIET])
This second signature is used to upload files to CDash via the CDash
file upload API. The API first sends a request to upload to CDash along
with a content hash of the file. If CDash does not already have the file,
then it is uploaded. Along with the file, a CDash type string is specified
to tell CDash which handler to use to process the data.
This signature interprets options in the same way as the first one.
.. versionadded:: 3.8
Added the ``RETRY_COUNT``, ``RETRY_DELAY``, ``QUIET`` options.
.. versionadded:: 3.9
Added the ``HTTPHEADER`` option.
.. versionadded:: 3.13
Added the ``RETURN_VALUE`` option.
.. versionadded:: 3.14
Added the ``SUBMIT_URL`` option.
.. versionadded:: 3.15
Added the ``BUILD_ID`` option.

329
cmake/share/cmake-3.30/Help/command/ctest_test.rst Normal file
View File

@ -0,0 +1,329 @@
ctest_test
----------
Perform the :ref:`CTest Test Step` as a :ref:`Dashboard Client`.
.. code-block:: cmake
ctest_test([BUILD <build-dir>] [APPEND]
[START <start-number>]
[END <end-number>]
[STRIDE <stride-number>]
[EXCLUDE <exclude-regex>]
[INCLUDE <include-regex>]
[EXCLUDE_LABEL <label-exclude-regex>]
[INCLUDE_LABEL <label-include-regex>]
[EXCLUDE_FROM_FILE <filename>]
[INCLUDE_FROM_FILE <filename>]
[EXCLUDE_FIXTURE <regex>]
[EXCLUDE_FIXTURE_SETUP <regex>]
[EXCLUDE_FIXTURE_CLEANUP <regex>]
[PARALLEL_LEVEL [<level>]]
[RESOURCE_SPEC_FILE <file>]
[TEST_LOAD <threshold>]
[SCHEDULE_RANDOM <ON|OFF>]
[STOP_ON_FAILURE]
[STOP_TIME <time-of-day>]
[RETURN_VALUE <result-var>]
[CAPTURE_CMAKE_ERROR <result-var>]
[REPEAT <mode>:<n>]
[OUTPUT_JUNIT <file>]
[QUIET]
)
..
NOTE If updating the argument list here, please also update the argument
list documentation for :command:`ctest_memcheck` as well.
Run tests in the project build tree and store results in
``Test.xml`` for submission with the :command:`ctest_submit` command.
The options are:
``BUILD <build-dir>``
Specify the top-level build directory. If not given, the
:variable:`CTEST_BINARY_DIRECTORY` variable is used.
``APPEND``
Mark ``Test.xml`` for append to results previously submitted to a
dashboard server since the last :command:`ctest_start` call.
Append semantics are defined by the dashboard server in use.
This does *not* cause results to be appended to a ``.xml`` file
produced by a previous call to this command.
``START <start-number>``
Specify the beginning of a range of test numbers.
``END <end-number>``
Specify the end of a range of test numbers.
``STRIDE <stride-number>``
Specify the stride by which to step across a range of test numbers.
``EXCLUDE <exclude-regex>``
Specify a regular expression matching test names to exclude.
``INCLUDE <include-regex>``
Specify a regular expression matching test names to include.
Tests not matching this expression are excluded.
``EXCLUDE_LABEL <label-exclude-regex>``
Specify a regular expression matching test labels to exclude.
``INCLUDE_LABEL <label-include-regex>``
Specify a regular expression matching test labels to include.
Tests not matching this expression are excluded.
``EXCLUDE_FROM_FILE <filename>``
.. versionadded:: 3.29
Do NOT run tests listed with their exact name in the given file.
``INCLUDE_FROM_FILE <filename>``
.. versionadded:: 3.29
Only run the tests listed with their exact name in the given file.
``EXCLUDE_FIXTURE <regex>``
.. versionadded:: 3.7
If a test in the set of tests to be executed requires a particular fixture,
that fixture's setup and cleanup tests would normally be added to the test
set automatically. This option prevents adding setup or cleanup tests for
fixtures matching the ``<regex>``. Note that all other fixture behavior is
retained, including test dependencies and skipping tests that have fixture
setup tests that fail.
``EXCLUDE_FIXTURE_SETUP <regex>``
.. versionadded:: 3.7
Same as ``EXCLUDE_FIXTURE`` except only matching setup tests are excluded.
``EXCLUDE_FIXTURE_CLEANUP <regex>``
.. versionadded:: 3.7
Same as ``EXCLUDE_FIXTURE`` except only matching cleanup tests are excluded.
``PARALLEL_LEVEL [<level>]``
Run tests in parallel, limited to a given level of parallelism.
.. versionadded:: 3.29
The ``<level>`` may be omitted, or ``0``, to let ctest use a default
level of parallelism, or unbounded parallelism, respectively, as
documented by the :option:`ctest --parallel` option.
``RESOURCE_SPEC_FILE <file>``
.. versionadded:: 3.16
Specify a
:ref:`resource specification file <ctest-resource-specification-file>`. See
:ref:`ctest-resource-allocation` for more information.
``TEST_LOAD <threshold>``
.. versionadded:: 3.4
While running tests in parallel, try not to start tests when they
may cause the CPU load to pass above a given threshold. If not
specified the :variable:`CTEST_TEST_LOAD` variable will be checked,
and then the :option:`--test-load <ctest --test-load>` command-line
argument to :manual:`ctest(1)`. See also the ``TestLoad`` setting
in the :ref:`CTest Test Step`.
``REPEAT <mode>:<n>``
.. versionadded:: 3.17
Run tests repeatedly based on the given ``<mode>`` up to ``<n>`` times.
The modes are:
``UNTIL_FAIL``
Require each test to run ``<n>`` times without failing in order to pass.
This is useful in finding sporadic failures in test cases.
``UNTIL_PASS``
Allow each test to run up to ``<n>`` times in order to pass.
Repeats tests if they fail for any reason.
This is useful in tolerating sporadic failures in test cases.
``AFTER_TIMEOUT``
Allow each test to run up to ``<n>`` times in order to pass.
Repeats tests only if they timeout.
This is useful in tolerating sporadic timeouts in test cases
on busy machines.
``SCHEDULE_RANDOM <ON|OFF>``
Launch tests in a random order. This may be useful for detecting
implicit test dependencies.
``STOP_ON_FAILURE``
.. versionadded:: 3.18
Stop the execution of the tests once one has failed.
``STOP_TIME <time-of-day>``
Specify a time of day at which the tests should all stop running.
``RETURN_VALUE <result-var>``
Store in the ``<result-var>`` variable ``0`` if all tests passed.
Store non-zero if anything went wrong.
``CAPTURE_CMAKE_ERROR <result-var>``
.. versionadded:: 3.7
Store in the ``<result-var>`` variable -1 if there are any errors running
the command and prevent ctest from returning non-zero if an error occurs.
``OUTPUT_JUNIT <file>``
.. versionadded:: 3.21
Write test results to ``<file>`` in JUnit XML format. If ``<file>`` is a
relative path, it will be placed in the build directory. If ``<file>``
already exists, it will be overwritten. Note that the resulting JUnit XML
file is **not** uploaded to CDash because it would be redundant with
CTest's ``Test.xml`` file.
``QUIET``
.. versionadded:: 3.3
Suppress any CTest-specific non-error messages that would have otherwise
been printed to the console. Output from the underlying test command is not
affected. Summary info detailing the percentage of passing tests is also
unaffected by the ``QUIET`` option.
See also the :variable:`CTEST_CUSTOM_MAXIMUM_PASSED_TEST_OUTPUT_SIZE`,
:variable:`CTEST_CUSTOM_MAXIMUM_FAILED_TEST_OUTPUT_SIZE` and
:variable:`CTEST_CUSTOM_TEST_OUTPUT_TRUNCATION` variables, along with their
corresponding :manual:`ctest(1)` command line options
:option:`--test-output-size-passed <ctest --test-output-size-passed>`,
:option:`--test-output-size-failed <ctest --test-output-size-failed>`, and
:option:`--test-output-truncation <ctest --test-output-truncation>`.
.. _`Additional Test Measurements`:
Additional Test Measurements
^^^^^^^^^^^^^^^^^^^^^^^^^^^^
CTest can parse the output of your tests for extra measurements to report
to CDash.
When run as a :ref:`Dashboard Client`, CTest will include these custom
measurements in the ``Test.xml`` file that gets uploaded to CDash.
Check the `CDash test measurement documentation
<https://github.com/Kitware/CDash/blob/master/docs/test_measurements.md>`_
for more information on the types of test measurements that CDash recognizes.
.. versionadded: 3.22
CTest can parse custom measurements from tags named
``<CTestMeasurement>`` or ``<CTestMeasurementFile>``. The older names
``<DartMeasurement>`` and ``<DartMeasurementFile>`` are still supported.
The following example demonstrates how to output a variety of custom test
measurements.
.. code-block:: c++
std::cout <<
"<CTestMeasurement type=\"numeric/double\" name=\"score\">28.3</CTestMeasurement>"
<< std::endl;
std::cout <<
"<CTestMeasurement type=\"text/string\" name=\"color\">red</CTestMeasurement>"
<< std::endl;
std::cout <<
"<CTestMeasurement type=\"text/link\" name=\"CMake URL\">https://cmake.org</CTestMeasurement>"
<< std::endl;
std::cout <<
"<CTestMeasurement type=\"text/preformatted\" name=\"Console Output\">" <<
"line 1.\n" <<
" \033[31;1m line 2. Bold red, and indented!\033[0;0ml\n" <<
"line 3. Not bold or indented...\n" <<
"</CTestMeasurement>" << std::endl;
Image Measurements
""""""""""""""""""
The following example demonstrates how to upload test images to CDash.
.. code-block:: c++
std::cout <<
"<CTestMeasurementFile type=\"image/jpg\" name=\"TestImage\">" <<
"/dir/to/test_img.jpg</CTestMeasurementFile>" << std::endl;
std::cout <<
"<CTestMeasurementFile type=\"image/gif\" name=\"ValidImage\">" <<
"/dir/to/valid_img.gif</CTestMeasurementFile>" << std::endl;
std::cout <<
"<CTestMeasurementFile type=\"image/png\" name=\"AlgoResult\">" <<
"/dir/to/img.png</CTestMeasurementFile>"
<< std::endl;
Images will be displayed together in an interactive comparison mode on CDash
if they are provided with two or more of the following names.
* ``TestImage``
* ``ValidImage``
* ``BaselineImage``
* ``DifferenceImage2``
By convention, ``TestImage`` is the image generated by your test, and
``ValidImage`` (or ``BaselineImage``) is basis of comparison used to determine
if the test passed or failed.
If another image name is used it will be displayed by CDash as a static image
separate from the interactive comparison UI.
Attached Files
""""""""""""""
.. versionadded:: 3.21
The following example demonstrates how to upload non-image files to CDash.
.. code-block:: c++
std::cout <<
"<CTestMeasurementFile type=\"file\" name=\"TestInputData1\">" <<
"/dir/to/data1.csv</CTestMeasurementFile>\n" <<
"<CTestMeasurementFile type=\"file\" name=\"TestInputData2\">" <<
"/dir/to/data2.csv</CTestMeasurementFile>" << std::endl;
If the name of the file to upload is known at configure time, you can use the
:prop_test:`ATTACHED_FILES` or :prop_test:`ATTACHED_FILES_ON_FAIL` test
properties instead.
Custom Details
""""""""""""""
.. versionadded:: 3.21
The following example demonstrates how to specify a custom value for the
``Test Details`` field displayed on CDash.
.. code-block:: c++
std::cout <<
"<CTestDetails>My Custom Details Value</CTestDetails>" << std::endl;
.. _`Additional Labels`:
Additional Labels
"""""""""""""""""
.. versionadded:: 3.22
The following example demonstrates how to add additional labels to a test
at runtime.
.. code-block:: c++
std::cout <<
"<CTestLabel>Custom Label 1</CTestLabel>\n" <<
"<CTestLabel>Custom Label 2</CTestLabel>" << std::endl;
Use the :prop_test:`LABELS` test property instead for labels that can be
determined at configure time.

43
cmake/share/cmake-3.30/Help/command/ctest_update.rst Normal file
View File

@ -0,0 +1,43 @@
ctest_update
------------
Perform the :ref:`CTest Update Step` as a :ref:`Dashboard Client`.
.. code-block:: cmake
ctest_update([SOURCE <source-dir>]
[RETURN_VALUE <result-var>]
[CAPTURE_CMAKE_ERROR <result-var>]
[QUIET])
Update the source tree from version control and record results in
``Update.xml`` for submission with the :command:`ctest_submit` command.
The options are:
``SOURCE <source-dir>``
Specify the source directory. If not given, the
:variable:`CTEST_SOURCE_DIRECTORY` variable is used.
``RETURN_VALUE <result-var>``
Store in the ``<result-var>`` variable the number of files
updated or ``-1`` on error.
``CAPTURE_CMAKE_ERROR <result-var>``
.. versionadded:: 3.13
Store in the ``<result-var>`` variable -1 if there are any errors running
the command and prevent ctest from returning non-zero if an error occurs.
``QUIET``
.. versionadded:: 3.3
Tell CTest to suppress most non-error messages that it would
have otherwise printed to the console. CTest will still report
the new revision of the repository and any conflicting files
that were found.
The update always follows the version control branch currently checked
out in the source directory. See the :ref:`CTest Update Step`
documentation for information about variables that change the behavior
of ``ctest_update()``.

26
cmake/share/cmake-3.30/Help/command/ctest_upload.rst Normal file
View File

@ -0,0 +1,26 @@
ctest_upload
------------
Upload files to a dashboard server as a :ref:`Dashboard Client`.
.. code-block:: cmake
ctest_upload(FILES <file>... [QUIET] [CAPTURE_CMAKE_ERROR <result-var>])
The options are:
``FILES <file>...``
Specify a list of files to be sent along with the build results to the
dashboard server.
``QUIET``
.. versionadded:: 3.3
Suppress any CTest-specific non-error output that would have been
printed to the console otherwise.
``CAPTURE_CMAKE_ERROR <result-var>``
.. versionadded:: 3.7
Store in the ``<result-var>`` variable -1 if there are any errors running
the command and prevent ctest from returning non-zero if an error occurs.

117
cmake/share/cmake-3.30/Help/command/define_property.rst Normal file
View File

@ -0,0 +1,117 @@
define_property
---------------
Define and document custom properties.
.. code-block:: cmake
define_property(<GLOBAL | DIRECTORY | TARGET | SOURCE |
TEST | VARIABLE | CACHED_VARIABLE>
PROPERTY <name> [INHERITED]
[BRIEF_DOCS <brief-doc> [docs...]]
[FULL_DOCS <full-doc> [docs...]]
[INITIALIZE_FROM_VARIABLE <variable>])
Defines one property in a scope for use with the :command:`set_property` and
:command:`get_property` commands. It is mainly useful for defining the way
a property is initialized or inherited. Historically, the command also
associated documentation with a property, but that is no longer considered a
primary use case.
The first argument determines the kind of scope in which the property should
be used. It must be one of the following:
::
GLOBAL = associated with the global namespace
DIRECTORY = associated with one directory
TARGET = associated with one target
SOURCE = associated with one source file
TEST = associated with a test named with add_test
VARIABLE = documents a CMake language variable
CACHED_VARIABLE = documents a CMake cache variable
Note that unlike :command:`set_property` and :command:`get_property` no
actual scope needs to be given; only the kind of scope is important.
The required ``PROPERTY`` option is immediately followed by the name of
the property being defined.
If the ``INHERITED`` option is given, then the :command:`get_property` command
will chain up to the next higher scope when the requested property is not set
in the scope given to the command.
* ``DIRECTORY`` scope chains to its parent directory's scope, continuing the
walk up parent directories until a directory has the property set or there
are no more parents. If still not found at the top level directory, it
chains to the ``GLOBAL`` scope.
* ``TARGET``, ``SOURCE`` and ``TEST`` properties chain to ``DIRECTORY`` scope,
including further chaining up the directories, etc. as needed.
Note that this scope chaining behavior only applies to calls to
:command:`get_property`, :command:`get_directory_property`,
:command:`get_target_property`, :command:`get_source_file_property` and
:command:`get_test_property`. There is no inheriting behavior when *setting*
properties, so using ``APPEND`` or ``APPEND_STRING`` with the
:command:`set_property` command will not consider inherited values when working
out the contents to append to.
The ``BRIEF_DOCS`` and ``FULL_DOCS`` options are followed by strings to be
associated with the property as its brief and full documentation.
CMake does not use this documentation other than making it available to the
project via corresponding options to the :command:`get_property` command.
.. versionchanged:: 3.23
The ``BRIEF_DOCS`` and ``FULL_DOCS`` options are optional.
.. versionadded:: 3.23
The ``INITIALIZE_FROM_VARIABLE`` option specifies a variable from which the
property should be initialized. It can only be used with target properties.
The ``<variable>`` name must end with the property name and must not begin
with ``CMAKE_`` or ``_CMAKE_``. The property name must contain at least one
underscore. It is recommended that the property name have a prefix specific
to the project.
Property Redefinition
^^^^^^^^^^^^^^^^^^^^^
Once a property is defined for a particular type of scope, it cannot be
redefined. Attempts to redefine an existing property by calling
:command:`define_property` with the same scope type and property name
will be silently ignored. Defining the same property name for two different
kinds of scope is valid.
:command:`get_property` can be used to determine whether a property is
already defined for a particular kind of scope, and if so, to examine its
definition. For example:
.. code-block:: cmake
# Initial definition
define_property(TARGET PROPERTY MY_NEW_PROP
BRIEF_DOCS "My new custom property"
)
# Later examination
get_property(my_new_prop_exists
TARGET NONE
PROPERTY MY_NEW_PROP
DEFINED
)
if(my_new_prop_exists)
get_property(my_new_prop_docs
TARGET NONE
PROPERTY MY_NEW_PROP
BRIEF_DOCS
)
# ${my_new_prop_docs} is now set to "My new custom property"
endif()
See Also
^^^^^^^^
* :command:`get_property`
* :command:`set_property`

10
cmake/share/cmake-3.30/Help/command/else.rst Normal file
View File

@ -0,0 +1,10 @@
else
----
Starts the else portion of an if block.
.. code-block:: cmake
else([<condition>])
See the :command:`if` command.

11
cmake/share/cmake-3.30/Help/command/elseif.rst Normal file
View File

@ -0,0 +1,11 @@
elseif
------
Starts an elseif portion of an if block.
.. code-block:: cmake
elseif(<condition>)
See the :command:`if` command, especially for the syntax and logic
of the ``<condition>``.

28
cmake/share/cmake-3.30/Help/command/enable_language.rst Normal file
View File

@ -0,0 +1,28 @@
enable_language
---------------
Enable languages (CXX/C/OBJC/OBJCXX/Fortran/etc)
.. code-block:: cmake
enable_language(<lang>... [OPTIONAL])
Enables support for the named languages in CMake. This is the same as
the :command:`project` command but does not create any of the extra
variables that are created by the :command:`project` command.
.. include:: SUPPORTED_LANGUAGES.txt
The following restrictions apply to where ``enable_language()`` may be called:
* It must be called in file scope, not in a function call.
* It must not be called before the first call to :command:`project`.
See policy :policy:`CMP0165`.
* It must be called in the highest directory common to all targets
using the named language directly for compiling sources or
indirectly through link dependencies. It is simplest to enable all
needed languages in the top-level directory of a project.
The ``OPTIONAL`` keyword is a placeholder for future implementation and
does not currently work. Instead you can use the :module:`CheckLanguage`
module to verify support before enabling.

20
cmake/share/cmake-3.30/Help/command/enable_testing.rst Normal file
View File

@ -0,0 +1,20 @@
enable_testing
--------------
Enable testing for current directory and below.
.. code-block:: cmake
enable_testing()
Enables testing for this directory and below.
This command should be in the source directory root
because ctest expects to find a test file in the build
directory root.
This command is automatically invoked when the :module:`CTest`
module is included, except if the ``BUILD_TESTING`` option is
turned off.
See also the :command:`add_test` command.

11
cmake/share/cmake-3.30/Help/command/endblock.rst Normal file
View File

@ -0,0 +1,11 @@
endblock
--------
.. versionadded:: 3.25
Ends a list of commands in a :command:`block` and removes the scopes
created by the :command:`block` command.
.. code-block:: cmake
endblock()

14
cmake/share/cmake-3.30/Help/command/endforeach.rst Normal file
View File

@ -0,0 +1,14 @@
endforeach
----------
Ends a list of commands in a foreach block.
.. code-block:: cmake
endforeach([<loop_var>])
See the :command:`foreach` command.
The optional ``<loop_var>`` argument is supported for backward compatibility
only. If used it must be a verbatim repeat of the ``<loop_var>`` argument of
the opening ``foreach`` clause.

14
cmake/share/cmake-3.30/Help/command/endfunction.rst Normal file
View File

@ -0,0 +1,14 @@
endfunction
-----------
Ends a list of commands in a function block.
.. code-block:: cmake
endfunction([<name>])
See the :command:`function` command.
The optional ``<name>`` argument is supported for backward compatibility
only. If used it must be a verbatim repeat of the ``<name>`` argument
of the opening ``function`` command.

14
cmake/share/cmake-3.30/Help/command/endif.rst Normal file
View File

@ -0,0 +1,14 @@
endif
-----
Ends a list of commands in an if block.
.. code-block:: cmake
endif([<condition>])
See the :command:`if` command.
The optional ``<condition>`` argument is supported for backward compatibility
only. If used it must be a verbatim repeat of the argument of the opening
``if`` clause.

14
cmake/share/cmake-3.30/Help/command/endmacro.rst Normal file
View File

@ -0,0 +1,14 @@
endmacro
--------
Ends a list of commands in a macro block.
.. code-block:: cmake
endmacro([<name>])
See the :command:`macro` command.
The optional ``<name>`` argument is supported for backward compatibility
only. If used it must be a verbatim repeat of the ``<name>`` argument
of the opening ``macro`` command.

14
cmake/share/cmake-3.30/Help/command/endwhile.rst Normal file
View File

@ -0,0 +1,14 @@
endwhile
--------
Ends a list of commands in a while block.
.. code-block:: cmake
endwhile([<condition>])
See the :command:`while` command.
The optional ``<condition>`` argument is supported for backward compatibility
only. If used it must be a verbatim repeat of the argument of the opening
``while`` clause.

30
cmake/share/cmake-3.30/Help/command/exec_program.rst Normal file
View File

@ -0,0 +1,30 @@
exec_program
------------
.. versionchanged:: 3.28
This command is available only if policy :policy:`CMP0153` is not set to ``NEW``.
Port projects to the :command:`execute_process` command.
.. deprecated:: 3.0
Use the :command:`execute_process` command instead.
Run an executable program during the processing of the CMakeList.txt
file.
.. code-block:: cmake
exec_program(Executable [directory in which to run]
[ARGS <arguments to executable>]
[OUTPUT_VARIABLE <var>]
[RETURN_VALUE <var>])
The executable is run in the optionally specified directory. The
executable can include arguments if it is double quoted, but it is
better to use the optional ``ARGS`` argument to specify arguments to the
program. This is because cmake will then be able to escape spaces in
the executable path. An optional argument ``OUTPUT_VARIABLE`` specifies a
variable in which to store the output. To capture the return value of
the execution, provide a ``RETURN_VALUE``. If ``OUTPUT_VARIABLE`` is
specified, then no output will go to the stdout/stderr of the console
running cmake.

171
cmake/share/cmake-3.30/Help/command/execute_process.rst Normal file
View File

@ -0,0 +1,171 @@
execute_process
---------------
Execute one or more child processes.
.. code-block:: cmake
execute_process(COMMAND <cmd1> [<arguments>]
[COMMAND <cmd2> [<arguments>]]...
[WORKING_DIRECTORY <directory>]
[TIMEOUT <seconds>]
[RESULT_VARIABLE <variable>]
[RESULTS_VARIABLE <variable>]
[OUTPUT_VARIABLE <variable>]
[ERROR_VARIABLE <variable>]
[INPUT_FILE <file>]
[OUTPUT_FILE <file>]
[ERROR_FILE <file>]
[OUTPUT_QUIET]
[ERROR_QUIET]
[COMMAND_ECHO <where>]
[OUTPUT_STRIP_TRAILING_WHITESPACE]
[ERROR_STRIP_TRAILING_WHITESPACE]
[ENCODING <name>]
[ECHO_OUTPUT_VARIABLE]
[ECHO_ERROR_VARIABLE]
[COMMAND_ERROR_IS_FATAL <ANY|LAST>])
Runs the given sequence of one or more commands.
Commands are executed concurrently as a pipeline, with the standard
output of each process piped to the standard input of the next.
A single standard error pipe is used for all processes.
``execute_process`` runs commands while CMake is configuring the project,
prior to build system generation. Use the :command:`add_custom_target` and
:command:`add_custom_command` commands to create custom commands that run
at build time.
Options:
``COMMAND``
A child process command line.
CMake executes the child process using operating system APIs directly:
* On POSIX platforms, the command line is passed to the
child process in an ``argv[]`` style array.
* On Windows platforms, the command line is encoded as a string such
that child processes using ``CommandLineToArgvW`` will decode the
original arguments.
No intermediate shell is used, so shell operators such as ``>``
are treated as normal arguments.
(Use the ``INPUT_*``, ``OUTPUT_*``, and ``ERROR_*`` options to
redirect stdin, stdout, and stderr.)
For **sequential execution** of multiple commands use multiple
``execute_process`` calls each with a single ``COMMAND`` argument.
``WORKING_DIRECTORY``
The named directory will be set as the current working directory of
the child processes.
``TIMEOUT``
After the specified number of seconds (fractions allowed), all unfinished
child processes will be terminated, and the ``RESULT_VARIABLE`` will be
set to a string mentioning the "timeout".
``RESULT_VARIABLE``
The variable will be set to contain the result of last child process.
This will be an integer return code from the last child or a string
describing an error condition.
``RESULTS_VARIABLE <variable>``
.. versionadded:: 3.10
The variable will be set to contain the result of all processes as a
:ref:`semicolon-separated list <CMake Language Lists>`, in order of the
given ``COMMAND`` arguments. Each entry will be an integer return code
from the corresponding child or a string describing an error condition.
``INPUT_FILE <file>``
``<file>`` is attached to the standard input pipe of the *first* ``COMMAND``
process.
``OUTPUT_FILE <file>``
``<file>`` is attached to the standard output pipe of the *last* ``COMMAND``
process.
``ERROR_FILE <file>``
``<file>`` is attached to the standard error pipe of *all* ``COMMAND``
processes.
.. versionadded:: 3.3
If the same ``<file>`` is named for both ``OUTPUT_FILE`` and ``ERROR_FILE``
then it will be used for both standard output and standard error pipes.
``OUTPUT_QUIET``, ``ERROR_QUIET``
The standard output on ``OUTPUT_VARIABLE`` or standard error on
``ERROR_VARIABLE`` are not connected (no variable content).
The ``*_FILE`` and ``ECHO_*_VARIABLE`` options are not affected.
``OUTPUT_VARIABLE``, ``ERROR_VARIABLE``
The variable named will be set with the contents of the standard output
and standard error pipes, respectively. If the same variable is named
for both pipes their output will be merged in the order produced.
``ECHO_OUTPUT_VARIABLE``, ``ECHO_ERROR_VARIABLE``
.. versionadded:: 3.18
The standard output or standard error will not be exclusively redirected to
the specified variables.
The output will be duplicated into the specified variables and also onto
standard output or standard error analogous to the ``tee`` Unix command.
.. note::
If more than one ``OUTPUT_*`` or ``ERROR_*`` option is given for the
same pipe the precedence is *not specified*.
If no ``OUTPUT_*`` or ``ERROR_*`` options are given the output will
be shared with the corresponding pipes of the CMake process itself.
``COMMAND_ECHO <where>``
.. versionadded:: 3.15
The command being run will be echo'ed to ``<where>`` with ``<where>``
being set to one of ``STDERR``, ``STDOUT`` or ``NONE``.
See the :variable:`CMAKE_EXECUTE_PROCESS_COMMAND_ECHO` variable for a way
to control the default behavior when this option is not present.
``ENCODING <name>``
.. versionadded:: 3.8
On Windows, the encoding that is used to decode output from the process.
Ignored on other platforms.
Valid encoding names are:
``NONE``
Perform no decoding. This assumes that the process output is encoded
in the same way as CMake's internal encoding (UTF-8).
This is the default.
``AUTO``
Use the current active console's codepage or if that isn't
available then use ANSI.
``ANSI``
Use the ANSI codepage.
``OEM``
Use the original equipment manufacturer (OEM) code page.
``UTF8`` or ``UTF-8``
Use the UTF-8 codepage.
.. versionadded:: 3.11
Accept ``UTF-8`` spelling for consistency with the
`UTF-8 RFC <https://www.ietf.org/rfc/rfc3629>`_ naming convention.
``COMMAND_ERROR_IS_FATAL <ANY|LAST>``
.. versionadded:: 3.19
The option following ``COMMAND_ERROR_IS_FATAL`` determines the behavior when
an error is encountered:
``ANY``
If any of the commands in the list of commands fail, the
``execute_process()`` command halts with an error.
``LAST``
If the last command in the list of commands fails, the
``execute_process()`` command halts with an error. Commands earlier in the
list will not cause a fatal error.

223
cmake/share/cmake-3.30/Help/command/export.rst Normal file
View File

@ -0,0 +1,223 @@
export
------
Export targets or packages for outside projects to use them directly
from the current project's build tree, without installation.
See the :command:`install(EXPORT)` command to export targets from an
install tree.
Synopsis
^^^^^^^^
.. parsed-literal::
export(`TARGETS`_ <target>... [...])
export(`EXPORT`_ <export-name> [...])
export(`PACKAGE`_ <PackageName>)
export(`SETUP`_ <export-name> [...])
Exporting Targets
^^^^^^^^^^^^^^^^^
.. signature::
export(TARGETS <target>... [...])
.. code-block:: cmake
export(TARGETS <target>... [NAMESPACE <namespace>]
[APPEND] FILE <filename> [EXPORT_LINK_INTERFACE_LIBRARIES]
[CXX_MODULES_DIRECTORY <directory>])
Creates a file ``<filename>`` that may be included by outside projects to
import targets named by ``<target>...`` from the current project's build tree.
This is useful during cross-compiling to build utility executables that can
run on the host platform in one project and then import them into another
project being compiled for the target platform.
The file created by this command is specific to the build tree and
should never be installed. See the :command:`install(EXPORT)` command to
export targets from an install tree.
The options are:
``NAMESPACE <namespace>``
Prepend the ``<namespace>`` string to all target names written to the file.
``APPEND``
Append to the file instead of overwriting it. This can be used to
incrementally export multiple targets to the same file.
``EXPORT_LINK_INTERFACE_LIBRARIES``
Include the contents of the properties named with the pattern
``(IMPORTED_)?LINK_INTERFACE_LIBRARIES(_<CONFIG>)?``
in the export, even when policy :policy:`CMP0022` is NEW. This is useful
to support consumers using CMake versions older than 2.8.12.
``CXX_MODULES_DIRECTORY <directory>``
.. versionadded:: 3.28
Export C++ module properties to files under the given directory. Each file
will be named according to the target's export name (without any namespace).
These files will automatically be included from the export file.
This signature requires all targets to be listed explicitly. If a library
target is included in the export, but a target to which it links is not
included, the behavior is unspecified. See the :command:`export(EXPORT)` signature
to automatically export the same targets from the build tree as
:command:`install(EXPORT)` would from an install tree.
.. note::
:ref:`Object Libraries` under :generator:`Xcode` have special handling if
multiple architectures are listed in :variable:`CMAKE_OSX_ARCHITECTURES`.
In this case they will be exported as :ref:`Interface Libraries` with
no object files available to clients. This is sufficient to satisfy
transitive usage requirements of other targets that link to the
object libraries in their implementation.
This command exports all :ref:`build configurations` from the build tree.
See the :variable:`CMAKE_MAP_IMPORTED_CONFIG_<CONFIG>` variable to map
configurations of dependent projects to the exported configurations.
Exporting Targets to Android.mk
"""""""""""""""""""""""""""""""
.. code-block:: cmake
export(TARGETS <target>... ANDROID_MK <filename>)
.. versionadded:: 3.7
This signature exports cmake built targets to the android ndk build system
by creating an ``Android.mk`` file that references the prebuilt targets. The
Android NDK supports the use of prebuilt libraries, both static and shared.
This allows cmake to build the libraries of a project and make them available
to an ndk build system complete with transitive dependencies, include flags
and defines required to use the libraries. The signature takes a list of
targets and puts them in the ``Android.mk`` file specified by the
``<filename>`` given. This signature can only be used if policy
:policy:`CMP0022` is NEW for all targets given. A error will be issued if
that policy is set to OLD for one of the targets.
Exporting Targets matching install(EXPORT)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
.. signature::
export(EXPORT <export-name> [...])
.. code-block:: cmake
export(EXPORT <export-name> [NAMESPACE <namespace>] [FILE <filename>]
[CXX_MODULES_DIRECTORY <directory>] [EXPORT_PACKAGE_DEPENDENCIES])
Creates a file ``<filename>`` that may be included by outside projects to
import targets from the current project's build tree. This is the same
as the :command:`export(TARGETS)` signature, except that the targets are not
explicitly listed. Instead, it exports the targets associated with
the installation export ``<export-name>``. Target installations may be
associated with the export ``<export-name>`` using the ``EXPORT`` option
of the :command:`install(TARGETS)` command.
``EXPORT_PACKAGE_DEPENDENCIES``
.. note::
Experimental. Gated by ``CMAKE_EXPERIMENTAL_EXPORT_PACKAGE_DEPENDENCIES``.
Specify that :command:`find_dependency` calls should be exported. See
:command:`install(EXPORT)` for details on how this works.
Exporting Packages
^^^^^^^^^^^^^^^^^^
.. signature::
export(PACKAGE <PackageName>)
.. code-block:: cmake
export(PACKAGE <PackageName>)
Store the current build directory in the CMake user package registry
for package ``<PackageName>``. The :command:`find_package` command may consider the
directory while searching for package ``<PackageName>``. This helps dependent
projects find and use a package from the current project's build tree
without help from the user. Note that the entry in the package
registry that this command creates works only in conjunction with a
package configuration file (``<PackageName>Config.cmake``) that works with the
build tree. In some cases, for example for packaging and for system
wide installations, it is not desirable to write the user package
registry.
.. versionchanged:: 3.1
If the :variable:`CMAKE_EXPORT_NO_PACKAGE_REGISTRY` variable
is enabled, the ``export(PACKAGE)`` command will do nothing.
.. versionchanged:: 3.15
By default the ``export(PACKAGE)`` command does nothing (see policy
:policy:`CMP0090`) because populating the user package registry has effects
outside the source and build trees. Set the
:variable:`CMAKE_EXPORT_PACKAGE_REGISTRY` variable to add build directories
to the CMake user package registry.
Configuring Exports
^^^^^^^^^^^^^^^^^^^
.. signature::
export(SETUP <export-name> [...])
.. code-block:: cmake
export(SETUP <export-name>
[PACKAGE_DEPENDENCY <dep>
[ENABLED (<bool-true>|<bool-false>|AUTO)]
[EXTRA_ARGS <args>...]
] [...]
[TARGET <target>
[XCFRAMEWORK_LOCATION <location>]
] [...]
)
.. versionadded:: 3.29
Configure the parameters of an export. The arguments are as follows:
``PACKAGE_DEPENDENCY <dep>``
.. note::
Experimental. Gated by ``CMAKE_EXPERIMENTAL_EXPORT_PACKAGE_DEPENDENCIES``.
Specify a package dependency to configure. This changes how
:command:`find_dependency` calls are written during
:command:`export(EXPORT)` and :command:`install(EXPORT)`. ``<dep>`` is the
name of a package to export. This argument accepts the following additional
arguments:
``ENABLED``
Manually control whether or not the dependency is exported. This accepts
the following values:
``<bool-true>``
Any value that CMake recognizes as "true". Always export the dependency,
even if no exported targets depend on it. This can be used to manually
add :command:`find_dependency` calls to the export.
``<bool-false>``
Any value that CMake recognizes as "false". Never export the dependency,
even if an exported target depends on it.
``AUTO``
Only export the dependency if an exported target depends on it.
``EXTRA_ARGS <args>``
Specify additional arguments to pass to :command:`find_dependency` after
the ``REQUIRED`` argument.
``TARGET <target>``
Specify a target to configure in this export. This argument accepts the
following additional arguments:
``XCFRAMEWORK_LOCATION``
Specify the location of an ``.xcframework`` which contains the library from
this target. If specified, the generated code will check to see if the
``.xcframework`` exists, and if it does, it will use the ``.xcframework``
as its imported location instead of the installed library.

28
cmake/share/cmake-3.30/Help/command/export_library_dependencies.rst Normal file
View File

@ -0,0 +1,28 @@
export_library_dependencies
---------------------------
Disallowed since version 3.0. See CMake Policy :policy:`CMP0033`.
Use :command:`install(EXPORT)` or :command:`export` command.
This command generates an old-style library dependencies file.
Projects requiring CMake 2.6 or later should not use the command. Use
instead the :command:`install(EXPORT)` command to help export targets from an
installation tree and the :command:`export` command to export targets from a
build tree.
The old-style library dependencies file does not take into account
per-configuration names of libraries or the
:prop_tgt:`LINK_INTERFACE_LIBRARIES` target property.
.. code-block:: cmake
export_library_dependencies(<file> [APPEND])
Create a file named ``<file>`` that can be included into a CMake listfile
with the INCLUDE command. The file will contain a number of SET
commands that will set all the variables needed for library dependency
information. This should be the last command in the top level
CMakeLists.txt file of the project. If the ``APPEND`` option is
specified, the SET commands will be appended to the given file instead
of replacing it.

1291
cmake/share/cmake-3.30/Help/command/file.rst Normal file
View File

File diff suppressed because it is too large Load Diff

48
cmake/share/cmake-3.30/Help/command/find_file.rst Normal file
View File

@ -0,0 +1,48 @@
find_file
---------
.. |FIND_XXX| replace:: find_file
.. |NAMES| replace:: NAMES name1 [name2 ...]
.. |SEARCH_XXX| replace:: full path to a file
.. |SEARCH_XXX_DESC| replace:: full path to named file
.. |prefix_XXX_SUBDIR| replace:: ``<prefix>/include``
.. |entry_XXX_SUBDIR| replace:: ``<entry>/include``
.. |FIND_XXX_REGISTRY_VIEW_DEFAULT| replace:: ``TARGET``
.. |FIND_PACKAGE_ROOT_PREFIX_PATH_XXX| replace::
``<prefix>/include/<arch>`` if :variable:`CMAKE_LIBRARY_ARCHITECTURE`
is set, and |FIND_PACKAGE_ROOT_PREFIX_PATH_XXX_SUBDIR|
.. |CMAKE_PREFIX_PATH_XXX| replace::
``<prefix>/include/<arch>`` if :variable:`CMAKE_LIBRARY_ARCHITECTURE`
is set, and |CMAKE_PREFIX_PATH_XXX_SUBDIR|
.. |CMAKE_XXX_PATH| replace:: :variable:`CMAKE_INCLUDE_PATH`
.. |CMAKE_XXX_MAC_PATH| replace:: :variable:`CMAKE_FRAMEWORK_PATH`
.. |ENV_CMAKE_PREFIX_PATH_XXX| replace::
``<prefix>/include/<arch>`` if :variable:`CMAKE_LIBRARY_ARCHITECTURE` is set,
and |ENV_CMAKE_PREFIX_PATH_XXX_SUBDIR|
.. |ENV_CMAKE_XXX_PATH| replace:: :envvar:`CMAKE_INCLUDE_PATH`
.. |ENV_CMAKE_XXX_MAC_PATH| replace:: :envvar:`CMAKE_FRAMEWORK_PATH`
.. |SYSTEM_ENVIRONMENT_PATH_XXX| replace:: The directories in ``INCLUDE``
and ``PATH``.
.. |SYSTEM_ENVIRONMENT_PATH_WINDOWS_XXX| replace::
On Windows hosts, CMake 3.3 through 3.27 searched additional paths:
``<prefix>/include/<arch>`` if :variable:`CMAKE_LIBRARY_ARCHITECTURE`
is set, and |SYSTEM_ENVIRONMENT_PREFIX_PATH_XXX_SUBDIR|.
This behavior was removed by CMake 3.28.
.. |CMAKE_SYSTEM_PREFIX_PATH_XXX| replace::
``<prefix>/include/<arch>`` if :variable:`CMAKE_LIBRARY_ARCHITECTURE`
is set, and |CMAKE_SYSTEM_PREFIX_PATH_XXX_SUBDIR|
.. |CMAKE_SYSTEM_XXX_PATH| replace::
:variable:`CMAKE_SYSTEM_INCLUDE_PATH`
.. |CMAKE_SYSTEM_XXX_MAC_PATH| replace::
:variable:`CMAKE_SYSTEM_FRAMEWORK_PATH`
.. |CMAKE_FIND_ROOT_PATH_MODE_XXX| replace::
:variable:`CMAKE_FIND_ROOT_PATH_MODE_INCLUDE`
.. include:: FIND_XXX.txt

96
cmake/share/cmake-3.30/Help/command/find_library.rst Normal file
View File

@ -0,0 +1,96 @@
find_library
------------
.. |FIND_XXX| replace:: find_library
.. |NAMES| replace:: NAMES name1 [name2 ...] [NAMES_PER_DIR]
.. |SEARCH_XXX| replace:: library
.. |SEARCH_XXX_DESC| replace:: library
.. |prefix_XXX_SUBDIR| replace:: ``<prefix>/lib``
.. |entry_XXX_SUBDIR| replace:: ``<entry>/lib``
.. |FIND_XXX_REGISTRY_VIEW_DEFAULT| replace:: ``TARGET``
.. |FIND_PACKAGE_ROOT_PREFIX_PATH_XXX| replace::
``<prefix>/lib/<arch>`` if :variable:`CMAKE_LIBRARY_ARCHITECTURE` is set,
and |FIND_PACKAGE_ROOT_PREFIX_PATH_XXX_SUBDIR|
.. |CMAKE_PREFIX_PATH_XXX| replace::
``<prefix>/lib/<arch>`` if :variable:`CMAKE_LIBRARY_ARCHITECTURE` is set,
and |CMAKE_PREFIX_PATH_XXX_SUBDIR|
.. |CMAKE_XXX_PATH| replace:: :variable:`CMAKE_LIBRARY_PATH`
.. |CMAKE_XXX_MAC_PATH| replace:: :variable:`CMAKE_FRAMEWORK_PATH`
.. |ENV_CMAKE_PREFIX_PATH_XXX| replace::
``<prefix>/lib/<arch>`` if :variable:`CMAKE_LIBRARY_ARCHITECTURE` is set,
and |ENV_CMAKE_PREFIX_PATH_XXX_SUBDIR|
.. |ENV_CMAKE_XXX_PATH| replace:: :envvar:`CMAKE_LIBRARY_PATH`
.. |ENV_CMAKE_XXX_MAC_PATH| replace:: :envvar:`CMAKE_FRAMEWORK_PATH`
.. |SYSTEM_ENVIRONMENT_PATH_XXX| replace:: The directories in ``LIB``
and ``PATH``.
.. |SYSTEM_ENVIRONMENT_PATH_WINDOWS_XXX| replace::
On Windows hosts, CMake 3.3 through 3.27 searched additional paths:
``<prefix>/lib/<arch>`` if :variable:`CMAKE_LIBRARY_ARCHITECTURE`
is set, and |SYSTEM_ENVIRONMENT_PREFIX_PATH_XXX_SUBDIR|.
This behavior was removed by CMake 3.28.
.. |CMAKE_SYSTEM_PREFIX_PATH_XXX| replace::
``<prefix>/lib/<arch>`` if :variable:`CMAKE_LIBRARY_ARCHITECTURE` is set,
and |CMAKE_SYSTEM_PREFIX_PATH_XXX_SUBDIR|
.. |CMAKE_SYSTEM_XXX_PATH| replace::
:variable:`CMAKE_SYSTEM_LIBRARY_PATH`
.. |CMAKE_SYSTEM_XXX_MAC_PATH| replace::
:variable:`CMAKE_SYSTEM_FRAMEWORK_PATH`
.. |CMAKE_FIND_ROOT_PATH_MODE_XXX| replace::
:variable:`CMAKE_FIND_ROOT_PATH_MODE_LIBRARY`
.. include:: FIND_XXX.txt
When more than one value is given to the ``NAMES`` option this command by
default will consider one name at a time and search every directory
for it. The ``NAMES_PER_DIR`` option tells this command to consider one
directory at a time and search for all names in it.
Each library name given to the ``NAMES`` option is first considered
as a library file name and then considered with platform-specific
prefixes (e.g. ``lib``) and suffixes (e.g. ``.so``). Therefore one
may specify library file names such as ``libfoo.a`` directly.
This can be used to locate static libraries on UNIX-like systems.
If the library found is a framework, then ``<VAR>`` will be set to the full
path to the framework ``<fullPath>/A.framework``. When a full path to a
framework is used as a library, CMake will use a ``-framework A``, and a
``-F<fullPath>`` to link the framework to the target.
.. versionadded:: 3.28
The library found can now be a ``.xcframework`` folder.
If the :variable:`CMAKE_FIND_LIBRARY_CUSTOM_LIB_SUFFIX` variable is set all
search paths will be tested as normal, with the suffix appended, and with
all matches of ``lib/`` replaced with
``lib${CMAKE_FIND_LIBRARY_CUSTOM_LIB_SUFFIX}/``. This variable overrides
the :prop_gbl:`FIND_LIBRARY_USE_LIB32_PATHS`,
:prop_gbl:`FIND_LIBRARY_USE_LIBX32_PATHS`,
and :prop_gbl:`FIND_LIBRARY_USE_LIB64_PATHS` global properties.
If the :prop_gbl:`FIND_LIBRARY_USE_LIB32_PATHS` global property is set
all search paths will be tested as normal, with ``32/`` appended, and
with all matches of ``lib/`` replaced with ``lib32/``. This property is
automatically set for the platforms that are known to need it if at
least one of the languages supported by the :command:`project` command
is enabled.
If the :prop_gbl:`FIND_LIBRARY_USE_LIBX32_PATHS` global property is set
all search paths will be tested as normal, with ``x32/`` appended, and
with all matches of ``lib/`` replaced with ``libx32/``. This property is
automatically set for the platforms that are known to need it if at
least one of the languages supported by the :command:`project` command
is enabled.
If the :prop_gbl:`FIND_LIBRARY_USE_LIB64_PATHS` global property is set
all search paths will be tested as normal, with ``64/`` appended, and
with all matches of ``lib/`` replaced with ``lib64/``. This property is
automatically set for the platforms that are known to need it if at
least one of the languages supported by the :command:`project` command
is enabled.

Some files were not shown because too many files have changed in this diff Show More