{"id":38788167,"url":"https://github.com/zenotech/common-superbuild","last_synced_at":"2026-01-17T12:35:46.813Z","repository":{"id":144916537,"uuid":"109316868","full_name":"zenotech/common-superbuild","owner":"zenotech","description":"https://gitlab.kitware.com/paraview/common-superbuild.git","archived":false,"fork":false,"pushed_at":"2025-08-20T10:28:53.000Z","size":3328,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":6,"default_branch":"master","last_synced_at":"2025-08-20T12:26:34.109Z","etag":null,"topics":["cmake","description","superbuild","superbuild-infrastructure"],"latest_commit_sha":null,"homepage":"","language":"CMake","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsd-3-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/zenotech.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2017-11-02T20:43:33.000Z","updated_at":"2025-08-04T11:03:11.000Z","dependencies_parsed_at":"2025-08-20T12:12:42.009Z","dependency_job_id":"954efeaf-1a98-4541-bb50-a92a951a908e","html_url":"https://github.com/zenotech/common-superbuild","commit_stats":null,"previous_names":[],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/zenotech/common-superbuild","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zenotech%2Fcommon-superbuild","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zenotech%2Fcommon-superbuild/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zenotech%2Fcommon-superbuild/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zenotech%2Fcommon-superbuild/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/zenotech","download_url":"https://codeload.github.com/zenotech/common-superbuild/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zenotech%2Fcommon-superbuild/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28508473,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-17T11:50:55.898Z","status":"ssl_error","status_checked_at":"2026-01-17T11:50:55.569Z","response_time":85,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cmake","description","superbuild","superbuild-infrastructure"],"created_at":"2026-01-17T12:35:46.714Z","updated_at":"2026-01-17T12:35:46.781Z","avatar_url":"https://github.com/zenotech.png","language":"CMake","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Common Superbuild Infrastructure\n\nThis project started as a refactor of a number of projects which had started\nusing the ParaView superbuild, but had diverged over time. Features were\nadded, patches trickled back and forth, but the gap needed to be closed. This\nrepository represents the common ground between all of them and aims to do so\nin a flexible way so that such gaps do not grow too large again.\n\n# Updating projects\n\nExisting projects are listed in `versions.cmake`, and generally point to an\narchive in [this spot](https://www.paraview.org/files/dependencies). Ask\nfor someone who has permissions to push an updated archive, then update\n`versions.cmake`. `md5sum` can calculate the hash for you.\n\nWhen updating a project please make sure to:\n\n - Consult the project .cmake file for any relevant comments\n - Check for any change in the CMake options in the release notes\n - Check for any licensing and copyright changes\n\n# Defining projects\n\nProjects are defined under the `projects/` hierarchy. Under this hierarchy,\nfiles with the name `$project.cmake` are created which define how to build the\nproject. Other files which have precedence include `$project.common.cmake`,\n`$project.functions.cmake`, and\n`$project.system.cmake`.\n\n  * `$project.common.cmake`: for projects which differ greatly based on the\n    platform, this is intended to be included by platform-specific files and\n    tweaked using variables.\n  * `$project.functions.cmake`: some projects might offer functions to\n    simplify things such as installation or testing. These functions should\n    be defined in a separate file so that they may be available during\n    packaging and testing as well.\n  * `$project.system.cmake`: projects may represent software packages which\n    are available as a system-wide copy (the `USE_SYSTEM` keyword); this file\n    is used to find the system copy and import it into the superbuild\n    infrastructure.\n\nDifferent platforms can shadow these files by using the following\nsubdirectories:\n\n  * Windows: `win32/`\n  * OS X: `apple/` and `apple-unix/`\n  * Linux: `unix/` and `apple-unix/`\n\nUsually these will just be the `$project.cmake` files, patches, and helper\nscripts, but it is not impossible that shadowing for the other files would be\nuseful.\n\nWhen adding a project, be sure to update:\n\n- `.gitlab/ci/configure_common.cmake`: enable (preferred) or suppress the\n  project's output\n- `selftest/CMakeLists.txt`: add the project to the list of projects\n- `selftest/tests/`: consider adding a test for the project (e.g., loading\n  Python modules)\n- `versions.cmake`: where to get the project's source\n\n### Dummy projects\n\nDummy projects exist to offer as a mechanism for users to access features. For\nexample, the `hdf5cpp` dummy project exists to request the C++ bindings of the\n`hdf5` project. Others exist to indicate a feature capability that may be\nrequired such as `cxx11` or `fortran`. At their core, dummy projects don't\nbuild anything but can instead modify behaviors of other projects by being\nenabled or disabled.\n\n## Related files\n\nSome projects might need support files such as patches or small scripts to\ncomplete some parts of the build step. For these files, the directories\n`patches/` and `scripts/` should be used. The files should start with the name\nof the project they are used for so that it is obvious why they exist.\nAdditionally, they should be underneath the directory for the `$project.cmake`\nfile which uses them. This keeps, e.g., Windows-specific patches underneath\nthe Windows platform directory.\n\nScripts should, preferably, be written in CMake code, but as a fallback,\nPython should be preferred since it is generally available. Shell and Batch\nscripts should be avoided.\n\n## Guidelines\n\nWithin a `$project.cmake` and related files, some guidelines should be\nfollowed:\n\n  - clear variables before use: the two-pass setup used by the superbuild may\n    cause variables to be non-empty on the second pass;\n  - prefix all variables and functions with the project name: variables such\n    as `extra_flags` and such might conflict with other projects;\n  - comment complicated logic: projects might need non-trivial logic to work\n    around weird bugs or other build failures; by documenting why this logic\n    exists, the idea is that time will not be needed to rediscover the reason\n    it exists.\n\n## ParaView Plugins\n\nParaView plugins are prevalent in superbuilds. There are support APIs in the\n[SuperbuildPluginMacros][plugin-macros] module.\n\nProjects which provide ParaView XML files may use the\n`superbuild_declare_paraview_xml_files` function to describe what plugin XML\nfiles will be installed by the project. Packaging may access this information\nvia the following variables:\n\n  - `projects_with_plugins`: A list of projects with associated plugin XML\n    variables set.\n  - `${project}_plugin_files`: A list of plugin XML files provided by the\n    project.\n  - `${project}_plugin_omit`: A list of plugins to omit from the XML files\n    (usually because they are static).\n\nProjects which consume plugins may use the\n`superbuild_omit_plugins_from_project` function to exclude plugins from a\nproject.\n\n## Examples\n\n*TODO*: Add some examples of projects.\n\n# Packages\n\nSuperbuilds may set the `superbuild_project_roots` variable to a list of paths\nin which to discover packages (represented as a directory) for the project.\nThese packages may provide a `\u003cpackage\u003e.configure.cmake` file which is included\nif it is selected as the primary package.\n\nThe default package is `\u003cnone\u003e`, but may be set via the\n`superbuild_package_default` variable.\n\nUsers may select a different default via the exposed `SUPERBUILD_PACKAGE_MODE`\ncache variable.\n\nPackages may set the `superbuild_extra_package_projects` variable to a list of\nprojects to include in the project as well.\n\n# Using the superbuild infrastructure\n\nTo create a new superbuild, a repository should be created which contains the\nsuperbuild infrastructure as a submodule. This allows updating to new versions\nof the common infrastructure easily and keeps the version which is being used\neasy to track.\n\nThere is only one required part (`superbuild_find_projects`), but other things\nwill generally be necessary for a new project, particularly\n`superbuild_project_roots` and `superbuild_version_files`. See below for more\nspecific information on these. After defining the functions and setting up the\nvariables, all that is required is to add the infrastructure's directory using\n`add_subdirectory`. It uses the functions and the variables values to do all\nof the required work. This setup is done so that the infrastructure can do\nwork in between all of the functions without application superbuild needing to\ncall the right functions in between the different steps.\n\n*Note*: For the purposes of the documentation, the new repository will be referred to\nas pertaining to an application to keep the use of the term \"project\" less\nambiguous. By no means is the superbuild limited to building end-user\napplications (though it is the primary use case).\n\n## `superbuild_find_projects` (function)\n\nThe core bit which is required by the superbuild infrastructure to work is a\nfunction called `superbuild_find_projects`. This function is used to populate\na variable (passed in as the argument) with the list of projects that are used\nfor the application. All projects which are required for the application\nshould be added to the list. As an example:\n\n```cmake\nfunction (superbuild_find_projects var)\n    set(projects\n        application dep1 dep2)\n\n    if (WIN32)\n        list(APPEND projects\n            depforwin32)\n    endif ()\n\n    set(\"${var}\" \"${projects}\" PARENT_SCOPE)\nendfunction ()\n```\n\nHere, the application depends on two other projects, `dep` and `dep2`.\nAdditionally, on Windows, `depforwin32` is also a dependency.\n\nThe superbuild infrastructure will only consider these projects to exist. Any\nother projects are completely ignored.\n\n## `superbuild_project_roots` (variable)\n\nThis variable is a list of directory paths to treat as roots to look for\n`$project.cmake` (and related) files. The relevant platforms will\nautomatically be searched for within each root. In addition, the common\ninfrastructure will put its project root at the end of this list.\n\nThe typical directory name for these roots is `projects/`. As an example:\n\n```cmake\nlist(APPEND superbuild_project_roots\n    \"${CMAKE_CURRENT_SOURCE_DIR}/projects\")\n```\n\n## `superbuild_version_files` (variable)\n\nThis variable is a list of files to include to declare version information for\nthe projects which will be built. The usual file name for these files is\n`versions.cmake`. The following functions will be available in the file:\n\n  - `superbuild_set_revision`\n  - `superbuild_set_customizable_revision`\n  - `superbuild_set_external_source`\n\nSee the [SuperbuildRevisionMacros][revision-macros] file for documentation on\nthese functions.\n\nThe common infrastructure will place its file at the end and it defines\nversion information for the projects it ships. Applications may override these\nversions by defining its own in a file in this list.\n\n## `superbuild_setup_variables` (function)\n\nThis function (though usually a macro), if defined, is called after revisions\nare defined, but before any projects are included. This is where project-wide\nvariables should be set so that they are available everywhere in the project.\n\nThis is usually where the `superbuild_set_version_variables` function is\ncalled (see the [SuperbuildVersionMacros][version-macros] file for its\ndocumentation) so that the application's version information is available at\nall times.\n\nThere is additionally the `superbuild_configure_project_version` function which\ncan extract more detailed version information from the project based on the\nsource selection in use. Special selection names:\n\n  - `source`: Local revision information will be extracted\n  - `git`: The repository's web hosting will be queried for version\n    information of the relevant commit.\n  - any other: Assumed to be the version number in question.\n\n## `superbuild_sanity_check` (function)\n\nThis function, if defined, is called after setting up the entire build. At\nthis stage, variables of the form `${project}_enabled` are available which\nindicate whether a project will be built or not. This function is the place to\ncheck whether project settings conflict with each other or whether an\nunsupported configuration has been chosen (e.g., not building the application,\nor choosing incompatible versions of Python).\n\n## Post-build tasks\n\nThe infrastructure supports running post-build tasks such as packaging and\ntesting. This uses CPack and CTest.\n\nThe preferred method to packaging is to set up an unrelated project which is\nbasically nothing except for installation logic. This is because CPack likes\nto rerun the installation of the top-level project before it runs which can\nretrigger builds of the main project. If projects are chasing branches in git\nand the branch has updated since the build and packaging, all of a sudden\nyou're packaging different code than you had built. As such, the old,\ndeprecated process is not documented here.\n\n### `superbuild_add_packaging` (function)\n\nThis function, if defined, should call the `superbuild_add_extra_package_test`\nfunction (see [SuperbuildPackageMacros][package-macros] for documentation) to\ncreate a test which will create a package using a specified generator. Tests\nare described by `$project.bundle.cmake` files in the project root\ndirectories.\n\nThe bundle files will have the following variables available:\n\n  - `superbuild_install_location`\n  - `superbuild_source_directory`\n  - `${project}_enabled`\n  - `USE_SYSTEM_${project}`\n\nIn addition, variables may be exported to the bundle project by setting the\n`superbuild_export_variables` variable to a list of variable names to add.\n\nSee the [SuperbuildInstallMacros][install-macros] file for documentation on\nthe variables available in `$project.bundle.cmake` files.\n\nPackage suffixes may be computed using the `superbuild_package_suffix`\nfunction, though this only supports basic information (version, platform, and\npointer size).\n\n### `superbuild_add_tests` (function)\n\nThis function, if defined, will enable testing for the superbuild itself.\nBefore testing is enabled, the `superbuild_setup_tests` hook is called (if\nset) so that any required variables may be set.\n\nAt the top-level (which should be fixed at some point; the function should do\nthis), the application may set the `superbuild_ctest_custom_files` variable to\na list of paths to `CTestCustom.cmake` files to be included during testing.\nWithin these files, convenience functions to ignore warnings and errors from\nprojects are provided:\n\n  - `ignore_project_warnings(project)`\n  - `ignore_project_errors(project)`\n\nThis may be used to silence warnings or errors from projects which cause noise\non the dashboard.\n\nIn addition, the `superbuild_test_projects` global property may be set to a\nlist of projects which should additionally be tested during a test of the\nsuperbuild. This will cause the project's tests to be available and run as\npart of a single top-level run of CTest. Cache variables named\n`TEST_${project}` will be added so that the user can disable this behavior. If\nthe project is either disabled or in a developer mode, the tests are similarly\nignored.\n\n## Advanced customization\n\n### `superbuild_install_location` (variable)\n\nThis variable is a path where all of the projects will install themselves. If\nit is not set, the default value is `${CMAKE_BINARY_DIR}/install`.\n\n### `mpi_ENABLE_UCX` (option)\n\nThis variable is useful for taking advantage of infiniband devices utilizing the\nchannel for ucx. This variable will typically be used in combination with the\n`mpi_EXTRA_CONFIGURE_ARGUMENTS` advanced variable to specify ucx settings\nduring the MPI build. By default this is disabled as most machines won't have\nthis high bandwidth option available and will just use regular ethernet for MPI\ncommunication.\n\n### `GENERATE_SPDX` (option)\n\nWhen this variable is turned on, the superbuild will generate a SPDX file for each\nproject and install it in `\u003cINSTALL_DIR\u003e/share/doc/${project}/spdx`. Warnings will\nbe outputed if any built project miss mandatory SPDX information. The SPDX document\nnamespace can be set using `superbuild_spdx_document_namespace` cmake variable and\ndefault to `https://kitware.com/spdx`.\nThese files could then be ultimely packaged as needed.\n\n### Flags\n\nThe common infrastructure will bring in flags from both the user's settings\nand the application. User settings are grabbed from the `CMAKE_C_FLAGS`,\n`CMAKE_CXX_FLAGS`, and `CMAKE_SHARED_LINKER_FLAGS` variables. Application\nflags use `superbuild_ld_flags`, `superbuild_cpp_flags`,\n`superbuild_cxx_flags`, and `superbuild_c_flags`.\n\n[install-macros]: cmake/SuperbuildInstallMacros.cmake\n[package-macros]: cmake/SuperbuildPackageMacros.cmake\n[plugin-macros]: cmake/SuperbuildPluginMacros.cmake\n[revision-macros]: cmake/SuperbuildRevisionMacros.cmake\n[version-macros]: cmake/SuperbuildVersionMacros.cmake\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzenotech%2Fcommon-superbuild","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fzenotech%2Fcommon-superbuild","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzenotech%2Fcommon-superbuild/lists"}