Re-introduce the behavior originally introduced in CMake 3.30.3 by
commit c1ece78d11 (project: non cache <project> prefix variables are
also created, 2024-08-27, v3.30.3~2^2), but this time with a policy for
compatibility.
Issue: #25714
Issue: #26243
The change in commit 86ad7cc886 (project: Only define non-cache vars if
already defined, 2024-09-15, v3.30.4~2^2) was meant to only check for
non-cache variables when deciding whether to set non-cache project
variables for the current call. However, it erroneously checked for any
variable, including cache variables. This gives the intended result on
the first run, but on subsequent runs a cache variable will exist that
did not on the first run, leading to different behavior between the two
runs. Fix the logic to only check for a pre-existing non-cache
variable, as was originally intended.
Fixes: #26355
In c1ece78d11 (project: non cache <project> prefix variables are
also created, 2024-08-27), we started explicitly setting the non-cache
variable for <projectName>_SOURCE_DIR, <projectName>_BINARY_DIR,
and <projectName>_IS_TOP_LEVEL in addition to setting them as
cache variables. This changed the behavior when a project name
was used more than once, and the second project call happens in
the same scope or a child scope of the first. Previously, the first
project call would set cache variables, and the second project call
would not overwrite those cache variables. With the change in
c1ece78d11, after the second project call the non-cache variables
would mask the cache variables and the project code would see
a different value to what it did before.
Setting the non-cache variable was added to handle the case where
a call to FetchContent_MakeAvailable() would set some non-cache
variables, and it just so happened those matched the same cache
variables that the project() command would set in the project being
fetched. The fetched project would then see a different set of
project-specific variables compared to when it was built standalone.
This commit here narrows the change from c1ece78d11 such that
the non-cache variable is only set by project() if there was already
a non-cache variable set. This still fixes the motivating problem
c1ece78d11 was intended to solve, but it avoids changing the variable
values seen by a project that re-uses the same project name in related scopes.
Issue: #26243, #25714Fixes: #26281
Specifically, the various CMAKE_PROJECT_...INCLUDE... variables can
now take a list of things, and those things can be module names
too, not just file names.
In commit b787be2714 (Help: Update supported languages in project and
enable_language, 2023-01-20, v3.26.0-rc1~53^2) the relevant paragraph
was accidentally moved to the `enable_language` command documentation.
Fixes: #25016
Define `PROJECT_IS_TOP_LEVEL` and `<PROJECT-NAME>_IS_TOP_LEVEL`. The
latter is a STATIC cache entry just like other `<PROJECT-NAME>_*`
variables so that it is globally scoped.
Issue: #20310Fixes: #21961
This change ony concerns directives that appear in the document body.
The guidelines for inserting version directives:
* Baseline version is CMake 3.0, i.e. directives start at 3.1.
* Always use `.. versionadded::` directive, avoid ad-hoc version
references. Exception: policy pages.
* For new command signatures, put `versionadded` on a separate line
after the signature.
* For a group of new signatures in a new document section,
a single version note at the beginning of the section is sufficient.
* For new options, put `versionadded` on a separate line before
option description.
* If all the option descriptions in the list are short one-liners,
it's fine to put `versionadded` on the same line as the description.
* If multiple option descriptions in close proximity would have
the same ..versionadded directive, consider adding a single
directive after the list, mentioning all added options.
* For compact value lists and sub-option lists, put a single
`versionadded` directive after the list mentioning all additions.
* When a change is described in a single paragraph, put
`versionadded` into that paragraph.
* When only part of the paragraph has changed, separate the changed
part if it doesn't break the flow. Otherwise, write a follow-up
clarification paragraph and apply version directive to that.
* When multiple version directives are close by, order earlier
additions before later additions.
* Indent related lists and code blocks to include them in the scope
of `versionadded` directive.
Issue: #19715
Follow up commit 0761186949 (project: Add variable
CMAKE_PROJECT_INCLUDE_BEFORE, 2019-03-28, v3.15.0-rc1~294^2) with a
project-specific variant. This variable will be used similar to the
already existing `CMAKE_PROJECT_INCLUDE_BEFORE` and
`CMAKE_PROJECT_<PROJECT-NAME>_INCLUDE` variables.
Fixes: #19854
Add entries in Modules and Modules/Platform to support
Objective-C++ compiler determination and identification.
Add Modules to check Objective-C++ compiler flags, source
compilations, program checks, etc...
Use OBJCXX as the designator of the language, eg:
project(foo OBJCXX)
Add various tests for Objective-C++ language features. Add
tests to preserve C++ handling of .M and .mm files when
Objective-C++ is not a configured language.
Co-authored-by: Cristian Adam <cristian.adam@gmail.com>
Add entries in Modules and Modules/Platform to support
Objective-C compiler determination and identification.
Add Modules to check Objective-C compiler flags, source
compilations, program checks, etc...
Use OBJC as the designator of the language, eg:
project(foo OBJC)
Add various tests for Objective-C language features. Add
tests to preserve C++ handling of .m and .mm files when
OBJC is not a configured language.
Co-Authored-By: Cristian Adam <cristian.adam@gmail.com>
If a project() call does not have DESCRIPTION or HOMEPAGE_URL
options, it must still set the relevant variables or else those variables will
inherit values from an earlier project() call. That is inconsistent with how
VERSION is handled and is likely to be unexpected. The docs were also
ambiguous about what should happen in such cases.
* Introduce `CMAKE_PROJECT_VERSION` and the corresponsing components:
`CMAKE_PROJECT_VERSION_MAJOR`, `CMAKE_PROJECT_VERSION_MINOR`,
`CMAKE_PROJECT_VERSION_PATCH` and `CMAKE_PROJECT_VERSION_TWEAK`.
* `CPack` module use `CMAKE_PROJECT_VERSION_MAJOR`,
`CMAKE_PROJECT_VERSION_MINOR` and `CMAKE_PROJECT_VERSION_PATCH`
to initialize corresponsing CPack variables.
This sets variables like PROJECT_HOMEPAGE_URL, which can be
used as default values for various things (packaging modules,
doxygen defaults, etc.). Some packaging modules have been
updated to do this as part of this commit.
Co-Author: Craig Scott <craig.scott@crascit.com>
The docs for CMAKE_PROJECT_NAME and CMAKE_PROJECT_DESCRIPTION
were erroneously documenting the behavior of PROJECT_NAME and
PROJECT_DESCRIPTION respectively. Fix these and update the
project() docs to also mention CMAKE_PROJECT_NAME and
CMAKE_PROJECT_DESCRIPTION.
Fixes: #17815
It is quite often the project description has used in a real world software.
Examples include:
* part of a help screen of the application
* builtin resources (`*.rc` files, data for "About" dialog of a GUI app, & etc)
* most generators for CPack can use it
* it could be used by documentary software (Doxygen, Sphinx) which is usually
integrated to CMake based projects via `add_custom_target()`
Now `project()` call learned an optional `DESCRIPTION` parameter with a
short string describing a project. Being specified, it would set the
`PROJECT_DESCRIPTION` variable which could be used in `configure_file()`
or whatever user wants. Also `PROJECT_DESCRIPTION` is a default value
for `CPACK_PACKAGE_DESCRIPTION_SUMMARY`.
Many projects put their project() call first, but the actions taken
by this command can be influenced by policies and other information
set by a call to cmake_minimum_required. Document in each of these
two commands that cmake_minimum_required should be called first.
Suggested-by: Alan W. Irwin
Teach the project() command to set variables
{PROJECT,<PROJECT-NAME>}_VERSION{,_MAJOR,_MINOR,_PATCH,_TWEAK}
holding the project version number and its components. Add project()
command option "VERSION" to specify the version explicitly, and default
to the empty string when it is not given.
Since this clears variables when no VERSION is given, this may change
behavior for existing projects that set the version variables themselves
prior to calling project(). Add policy CMP0048 for compatibility.
Suggested-by: Alex Neundorf <neundorf@kde.org>
Teach the project() command to recognize an optional "LANGUAGES"
keyword after the project name and prior to the list of languages.
Do not allow multiple copies of the keyword. If the keyword is
specified and no languages are listed, imply NONE.
