Package: illyrian
IllyrianIllyrian is CMake extension for easily creating Python packages. The drawback of
setuptools is that it is supposed to be encapsulate CMake. However, if your
CMake produces multiple Python libraries, you would need to split your CMake
project. With Illyrian you don't need to do it! With Illyrian CMake encapsulates
the Python Wheel build process!Release NotesVersionCommentv0.3.3Increase CMake backward compatibility forEXECUTE_PROCESS(...)v0.3.2Added cpython3.11 symbols.BugfixPython3_USERLIBdetection.v0.3.1CMake ignoresPython3_USERLIBwhen USER_SITE is disabled.Fixed `TypeError: '<' not supported between instances of 'NoneType' and 'NoneType'`.v0.3.0Improved error handling within CMake extensionAdded version number format checkingIncreased CMake min version to 3.19Added support to run multiple files at once:illyrian A.json B.json C.jsonFixed hashing for dist-info/RECORDv0.2.2Added option to fetch name + email fromgitusing '__GIT__' valueFixed bug where Illyrian deleted all WHL in the target folderAdded Python 3.6 compatibilityv0.2.1AddedILLYRIAN_NO_PYTHONoption to CMake for non-python builds that use Illyrianv0.2.0**BREAKING CHANGE**Changed optional syntax to allow conditionals such as/some/path/pattern*.* ? >= 5 && <7Illyrian now automatically determines your Manylinux and CPython compatibility if you don't explicitly set it viaabi-tagandplatform-tag.AddedEXACTkeyword toILLYRIAN_FIND_PYTHONFixed generation ofRECORDfile when package contains script filesGenerated FindScripts now recheck if the version number gets increasedAddedILLYRIAN_PYTHON_VERSIONenv var to override default version forILLYRIAN_FIND_PYTHON.Addedlicense-fileoption.Addedlinksoption, that allows to add links to executables.v0.1.4Removed-Wl,--no-as-neededfromILLYRIAN_TARGET_FLAGS.Fixed uninitialized var inILLYRIAN_TARGET_FLAGSv0.1.3Split "tag" into "abi-tag" and "platform-tag" as described inPEP491.v0.1.2Improved Illyrian command argument parsing.v0.1.1AddedEXACTtoILLYRIAN_FIND_PYTHONv0.1.0Initial ReleaseHow to build?git clone ...
cmake3 -S illyrian -B illyrian/build

# Build in ${CMAKE_BINARY_DIR}/dist
cmake3 --build illyrian/build --target install

# Build WHEEL
cmake --build illyrian/build --target dist

# Build WHEEL and immediately install
cmake --build illyrian/build --target dist-installInstalling IllyrianEither follow the building steps or just runpip3 install illyrian.Setting up your CMake projectIn order to setup your CMake project, it needs to contain:FIND_PACKAGE(Illyrian0.1REQUIRED)After this line you can use all CMake Illyrian functions. To properly setup your
project you either need to manually set theCMAKE_MODULE_PATHto/path/to/illyrian/cmake/or just runillyrian cmake arg0 arg1 arg1 ... path/to/srcAvailable CMake commands:ILLYRIAN_PROJECT([C_STANDARD int] [CXX_STANDARD int] [INSTALL_PREFIX str] [SUPPORTED_OS list(str)])Convenience wrapper for easier setup of C/C++ CMake projects.SUPPORTED_OSchecks for matching strings inCMAKE_HOST_SYSTEM_NAME.INSTALL_PREFIXsets the defaultCMAKE_INSTALL_PREFIXif non is
provided by the user or project itself.ILLYRIAN_FIND_PYTHON([VERSION version])Searches for Python and additionally setsPython3_USERLIBto.local/lib/.../site-packages.VERSIONcan be used to define a
minimum Python version, default is 3.7.ILLYRIAN_INSTALL_PYTHON_PACKAGE(list(str))Installs the mentioned package using${Python3_EXECUTABLE} -m pip install .... ExecutesILLYRIAN_FIND_PYTHON()if was not run before.ILLYRIAN_FIND_PACKAGE(NAME [REQUIRED] [VERSION version] [PATHS list(str)] [PYTHON list(str)])Convenience wrapper forFIND_PACKAGE(...)that not only looks in the provided list of paths (i.e.PATHS /usr/local/bla), but also in Python packages (i.e.PYTHON my_project/cmake).Some examples:ILLYRIAN_FIND_PACKAGE(TunglVERSION0.1REQUIREDPYTHON"tungl/cmake"PATHS"/usr/local/nle/tungl/cmake")ILLYRIAN_FIND_PACKAGE(VEDAVERSION1.3REQUIREDPYTHON"veda/cmake"PATHS"/usr/local/ve/veda/cmake")ILLYRIAN_FIND_PACKAGE(VEDATensorsVERSION0.1REQUIREDPYTHON"veda/tensors/cmake"PATHS"/usr/local/ve/veda-tensors/cmake")ILLYRIAN_INSTALL_SYMLINK(DST SRC [DIRECTORY] [PYTHON] [DESTINATION])Creates a Symlink during installation of project.DIRECTORYindicates a
directory symlink.DESTINATIONthe installation folder where to place the
symlink.PYTHONactivates Python packaging. As Python wheels don't support symlinks Illyrian instead creates a linker file that can be used for linking, but no
other purposes.ILLYRIAN_OPTIONS(NAME list(str))Convenience wrapper to create list options for CCMake.ILLYRIAN_TARGET_OPTIONS(NAME [LINK_MAP] [PYTHON] [SOVERSION version] [DESTINATION str] [COMPILE_OPTIONS list(str)] [LINK_FLAGS list(str)] [PYTHON_RPATH list(str)] [RPATH list(str)])Convenience wrapper that packages C/C++ executables + libraries.LINK_MAP: will use the version-script${NAME}.mapin the current folder when linking the project.PYTHON: activates Python packaging of this target.SOVERSION: Sets the SOversion of the project. In normal mode, it creates symlinks likelibbla.so -> libbla.so.1 -> libbla.so.1.2.3. In Python mode it creates the library aslibbla.so.1and creates linker scriptslibbla.soandlib.bla.so.1.2.3that point tolibbla.so.1.DESTINATION: Path to install the target to.COMPILE_OPTIONS: Sets the target's compile options.LINK_FLAGS: Sets the target's linker flags.PYTHON_RPATH: RPATHs used when Python packaging.RPATH: Normal RPATHs.ADD_PYTHON_WHEEL(TARGET_NAME JSON)Reads the Illyrian config fileJSONcan creates the targets${TARGET_NAME}and${TARGET_NAME}-install. The first compiles the
Python Wheel, the second additionally installs it usingpython3 -m pip install .... The JSON file will be configured by CMake using the@ONLYoption, so you can i.e. set the version as"version": "@MyProject_VERSION@".ILLYRIAN_INSTALL_FIND*TheILLYRIAN_INSTALL_FIND*methods can be used to create customized find scripts for your project.# creates a new Find${NAME}.cmakeILLYRIAN_INSTALL_FIND_BEGIN(NAME# Find${NAME}.cmake[PYTHON_NAMEstr]# name of the project in Python notation (usually lowercase)[FILEstr]# a file used to determine the ${NAME}_DIR[PYTHON_VERSIONversion]# min Python Version required by the find script[PATHSlist(str)]# list of folders to look for FILE)# add FIND_${TYPE}(${NAME}_${VAR} ...) to the find scriptILLYRIAN_INSTALL_FIND_OPTIONAL(TYPENAMEVAR...)# same as ..._OPTIONAL but will fail if not foundILLYRIAN_INSTALL_FIND_REQUIRED(TYPENAMEVAR...)# adds SET(${NAME}_${VAR} ...) to the find scriptILLYRIAN_INSTALL_FIND_SET(NAMEVAR...)# finalizes the find scriptILLYRIAN_INSTALL_FIND_END(NAME# Project Name[DESTINATIONstr]# path for installation of the find script[VERSION_FILEstr]# file that gets read for extracting the version i.e. "include/version.h"[VERSION_REGEXstr]# CMake Regex to extract the version from VERSION_FILE[APPENDlist(str)]# list of commands that just get appended to the find script)ILLYRIAN_INCLUDE_DIRECTORIES([TARGETS list(targets] [PATHS list(paths)]))Convenience wrapper to setINCLUDE_DIRECTORIESby paths and target names.ILLYRIAN_FIND_PYTHON_[PATH, FILE](VAR NAME FILE [PATHS list(str)])SearchesFILEin the Python packageNAMEgiven the foldersPATHSand stores the PATH or FILE inVAR.Manually running IllyrianYou can use Illyrian also without CMake. For this just runillyrian your_config.jsonin the root folder of your project.Illyrian Config FileThe Illyrian config file is a plain JSON file that supports the following fields. Seehttps://peps.python.org/pep-0345/for explanation of the fields.FieldsTypeComment__include__str/listAllows to include other config JSON files. If a key exists in both, the value will be casted to a list and get appended.abi-tagstrdefault: autoauthorstrauthor-emailstrclassifierstr/listdownload-urlstrhomepagestrkeywordsstrlicensestrlicense-filestrWill be stored in package-name.dist/LICENSElinkslistCreates global links to executables.maintainerstrmaintainer-emailstrnamestrrequiredobsoletes-diststr/listplatformstr/listplatform-tagstrdefault: autoproject-urlstr/listprovides-diststr/listprovides-extrastr/listreadmepath/to/readme.mdExpects the path to a Markdown file. The file DOES NOT get stored within the wheel. Usepayloadfor that.requires-diststr/listrequires-externalstr/listrequires-python>= 3.Xrequiredsummarystrrequiredsupported-platformstr/listversion[0-9\.]+requiredAdditionally there thepackageskey expects a list of paths to python
packages, i.e."packages": ["bla", "bla/sub"]. ALL subpackages need to be
manually specified AND only*.pyfiles will be includes.Thepayloadkey expects a list of paths. Here you can use GLOB syntaxpath/to/*.hor use**for recursive inclusion, i.e.,path/to/**.packagesandpayloadfail if no files are found in the specified
path. This can be overwritten by adding an?with a condition (```>=, <=,, <, ==, !=) and the number of expected files, e.g.,/my/path/* ? ==
5. You can chain multiple and-conditions using&&```.Here an example:{"name":"illyrian","version":"@Illyrian_VERSION@","platform":"linux_x86_x64","summary":"Illyrian is CMake extension for easily creating Python packages.","readme":"illyrian/README.md","author":"User Name <user.name@company.com>","license":"3 BSD-License","requires-python":">=3.7","packages":["illyrian"],"payload":["illyrian/LICENSE","illyrian/cmake/*.cmake"],"scripts":["scripts/illyrian"]}Illyrian Debug FeaturesIf you want to investigate the meta data of a WHL file, just runillyrian file.whl. Illyrian will extract all available metadata (.dist-info/METADATA,
WHEEL and RECORD) and evaluate also the correctness of the entries within the
RECORD file.