Repository files navigation

Look through the files in the package. Most functions will be commented and the other's usage can be inferred. All functions are available as soon as you include thecmakepp.cmake file. To find functionality browse theREADME.md files throughout this project.

cmakepp has a lot of different functions. I tried to subdivide them into some meaningful sections.

• Buildserver
• Creating Checksums
• CMake handling functions
• Collections
• Date/Time
• Events
• cmakepp Expression Syntax
• Filesystem
• Functions
• Logging Functions
• Maps - Structured Data in CMake
• Navigation Functions
• Objects
• Dependency Management
• User Data
• Process Management
• Quick Map Syntax
• Reference Values
• Windows Registry
• Parsing and handling semantic versions
• String Functions
• Tasks and Promises
• Templating
• Uniform Resource Identifiers (URIs)
• HTTP Client

I have developed some samples to show offcmakepp's capabilities. Here you can find an overview of these samples

https://github.com/open-source-parsers/jsoncpp/archive/1.6.0.tar.gzhttps://github.com/leethomason/tinyxml2/archive/2.2.0.tar.gzhttps://yaml-cpp.googlecode.com/files/yaml-cpp-0.5.1.tar.gz

• Compiling a simple progam by includingcmakepp and pullingeigen library
• Including and usingcmakepp inCMakeLists.txt
• Downloading and Includingcmakepp in aCMakeLists.txt
• Creating a Compressed Package
• Creating and Installing a Package with an Install Hook
• Installing and Using Projects with vanillaCMake
• Working with Packages
• Using theCMakeLists Generator - CMake Reflection
• Dynamic Calls, Return Values and Exceptions

You have multiple options to installcmakepp the only prerequisite for all options is thatCMake is installed with a version>=2.8.12.cmakepp will also work with version less than2.8.12 however some functions might fail.

• Install by Console - Recommended
• Use theBiicode Block
• Download a release and include it in your cmake script file - If you do not want to run the tests or have access to the single function files this option is for you.
  • Manually setup aliases
• Clone the repository and includecmakepp.cmake in yourCMakeLists.txt (or other cmake script)

For ease of use I provide you with simple copy paste code for your console of choice. These scripts download theinstall.cmake file and execute it. This file in turn downloadscmakepp and adds itself to your os (creating aliases and setting a environment variable - which allow you to useicmakepp andcmakepp cli from the console).

Bash

#!bin/bashwget https://raw.github.com/toeb/cmakepp/master/install.cmake && cmake -P install.cmake && rm install.cmake

Powershell

((new-object net.webclient).DownloadString('https://raw.github.com/toeb/cmakepp/master/install.cmake')) |`out-file -Encoding ascii install.cmake; `cmake -P install.cmake; `rm install.cmake;

You can go ahead and download the current release fromhere. A release supplies you with a standalone version ofcmakepp which contains every function ofcmakepp. This standalone file can be included in any of yourCMake scripts.

The following code shows you how you can retrieve and include it in any of your script files.

## downloads and includes `cmakepp.cmake` if(NOT EXISTS "cmakepp.cmake")  file(DOWNLOAD "https://github.com/toeb/cmakepp/releases/download/v0.0.4/cmakepp.cmake" "cmakepp.cmake")endif()include("cmakepp.cmake")

cmake -P ./cmakepp.cmake cmakepp_setup_environment

After You run this and relogin/repoen your console/resource your .bashrc you will have access to the aliascmakepp,icmakepp,pkg,cml. Also the environment variableCMAKEPP_PATH will be set to the location werecmakepp.cmake resides.

To test the code (alot is tested but not all) run the following in the root dir of cmakeppthis takes long :)

cmake -P build/script.cmake

If you want to help to developecmakepp or want to developeCMake scripts which usecmakepp you can do the following:

• Install Sublime Text 3
• Be sure you have thecmakepp repository checked out
• open thecmakepp.sublime-project project in sublime text
• (add the folder in which you are developing your scripts)
• select the correct build system
  • cmakepp run test will run the current script open in SublimeText file as a test. It does not matter were this file resides. It expects a single function to exist inside this file - the name does not matter as it will be imported. Inside the test function you will be provided with the following (also seetest_execute:
    • allcmakepp functions will be loaded from your current version of cmakepp.
    • a timer will run and report the time in milliseconds that your test tookNOTE this is not very exact but sufficient in most cases
    • ${test_dir} contains the the path of an empty directory which will remain the same for that specific test. It is cleared before the test is run so you can write anything to it and do not have to care about housekeeping.
    • the<pwd> will be set to${test_dir} allowing you to start using allcmakepp file/process functions relative to the test directory
    • ${test_name} will contain the name chosen for this test (filename w/o extension)
  • cmakepp run all tests will run each test incmakepp
  • cmakepp template run will execute acmakepp template file of which the filename ends with.in (seetemplating)
  • you can open thecmakepp.sublime-project and modify the build system.

I have two persistant branches:master anddevel. Then there are an arbitrary amount of volatile branches which are used to develope features / remote store developements. Themaster branch is only merged fromdevel and always is always stable - ie the build server determines that all tests were successfull. Thedevel branch is also built build servers but may sometime be in the failed state. The volatile branches are just used to develop and are not built - as to not clutter up the build servers with uneccessary builds.

I would be very happy If you choose to contribute tocmakepp. You can open any issue on github and I will try to reply as soon as possible. I care about any feature you want implemented, bug you want squashed, or modification.

If you want to change something you may send pull requests through github. Normally I will check them quickly andtravis-ci will build them. I suggest you run all tests using the sublime project before you create a pull request to see if anything breaks. (the master branch will have to pass the tests)

Also if you want to support me financially for all the hardwork - consider donating a couple of $

I am a bit a hypocrit. I am trying to adhere to these rules though:

• DO NOT USE SHOUTY SYNTAX
• test your code. A single test file will suffice it should cover normal use cases and edge cases. I use tests for documentation.
• One file per function.
• Create a comment header with markdown above the function(with 2 # ).
• put the function in the most suitable folder.
• name the function in a none colliding way
  • CMake only has a global scope for functions. Therefore be sure to name them in a way that they do not collide with existing functions and will not in the future.
• usesnake_case for function names.CMake's functions are case independent so I discourage usingcamelcase

Note:This section is incomplete but will give you an idea how I formally define data and functions.

To describe cmake functions I use formalisms which I found most useful they should be intuitively understandable but here I want to describe them in detail.

• @ denotes character data
• <string> ::= "\""@"\"" denotes a string literal
• <regex> ::= "/" <string> "/" denotes a regular expression which needs to match
• <identifier> ::= /[a-zA-Z_][a-zA-Z0-9_]*/ denotes a identifier which can be used for definitions
• <datatype> ::= "<" "any"|"bool"|"number"|""|"void"|""|<structured data> <?"...">">" denotes a datatype. the elipses denotes that multiple values in array form are described else the datatype can beany,bool,number,<structured data> etc..
• <named definition> ::= "<"<identifier>">"
• <definition> ::= "<" "?"? <identifier>"&"?|<identifier>"&"?":"<datatype>|<datatype>> ("=" ">" denotes a possibly named piece of data. this is used in signatures and object descriptions e.g.generate_greeting(<firstname:<string>> <?lastname:<string>>)-><string> specifies a function which which takes a required parameter calledfirst_name which is of typestring and an optional parameter calledlastname which is of typestring and returns astring
  • & indicates that the identifier is a reference - a variable exists with the name passed in the named identifier
  • ? indicates optionality (no need to specify the value)
  • `= indicates the default value which is used when the specified value is not specified
• <structured data> ::= "{"<keyvalue:(<named definition>|(<identifier>":"<datatype>))...>|"}" the structured date is sometimes multiline
  • { <name:<string>> <age:<int>> }
  • { name:<string> age:<int>}
  • { name:<string> address:{ street:<string> area_code:<string>} age:<int>}
  • { <<group:<string>>:<users:<string...>> ...> } describes a map which contains keys of type string which identify a group and associated values which are a string list representing users
• <void> primitive which stands for nothing
• <null> ::= "" primitive which is truely empty (a string of length0)
• <falseish>:"false"|""|"no" cmake's false values (list incomplete)
• <trueish>: !<falseish>
• <bool> ::= "true":"false" indicates a well defined true or false value
• <boolish> ::= <trueish>|<falsish>|<bool>
• <any> ::= <string>|<number>|<structured data>|<bool>|<void>
• <value identifier> ::= /a-zA-Z0-9_-/+
• <named function parameter>::= "<"|"["<value identifier> (<definition>="<any>")?"]"|">" specifies a named function parameter. avalue identifier without adefinition causes the named function parameter to be a flag a boolean is derived which istrue if the flag exists, elsefalse.
  • [--my-flag] a flag
  • [--depth <n:int>] a optional value
  • <--depth <n:int>> a required value
• <function parameter> ::= <definition>|<named function parameter>
• <function definition> ::= ("["<scope inheritance>"]")?"("<function parameter...>")" "->" <function parameter>("," <side effects>)?
  • (<any>)-><bool> a function expecting a single<any> element and returning a<bool>
  • (<any...>)-><string...> a function taking a variable amount of any and returning a list of strings
  • [<depth:int>](<node:<any>>)-><node...> a function taking a variable node of type<any> which returns a list of<node> expects a variabledepth to be defined in parent scope which needs to be a integer
  • ...

Related Functions

• return(...) overwritten CMake function accepting arguments which are returned
• ans(<var>) a shorthand for getting the result of a function call and storing it in var
• clr([PARENT_SCOPE]) clears the__ans variable in current scope or in PARENT_SCOPE if flag is set.

A CMake function can return values by accessing it's parent scope. Normally one does the following to return a value

  function(myfunc result)    set(${result} "return value" PARENT_SCOPE)  endfunction()  myfunc(res)  assert(${res} STREQUAL "return value")

This type of programming causes problems when nesting functions as one has to return every return value that a nested function returns. Doing this automatically would cause alot of overhead as the whole scope would have to be parsed to see which values are new after a function call.

A cleaner alternative known from many programming languages is using a return value. I propose and have implemented the following pattern to work around the missing function return values of cmake.

  function(myfunc)    return("return_value")  endfunction()  myfunc()  ans(res)  # the __ans var is used as a register  assert(${__ans} STREQUAL "return value")  assert(${res} STREQUAL "return value")

This is possible by overwriting CMakes default return() function with a macro. It accepts variables and will callset(__ans ${ARGN} PARENT_SCOPE) so after the call tomyfunc() the scope will contain the variable__ans. using theans(<var>) function is a shorthand forset(<var> ${__ans}).

• The returnvalue should immediately be consumed after the call tomyfunc because it might be reused again somewhere else.
• functions which do not call return will not set__ans in their parent scope. If it is unclear weather a function really sets__ans you may want to clear it before the function call usingclr()
• the overwrite forreturn has to be a macro, else accessing thePARAENT_SCOPE would be unfeasible. However macros caus the passed arguments to be re-evaluated which destroys some string - string containing escaped variables or other escaped characters. This is often a problem - therfore I have als added thereturn_ref function which accepts a variable name that is then returned.

• a stack machine would also be a possiblity as this would allow returning multiple values. I have decided using the simpler single return value appoach as it is possible to return a structured list or a map if multiple return values are needed.

cmakepp can be used as a platform independent console application. When you startcmakepp.cmake in script mode it parse the passed command line arguments and execute the specifiedcmakepp function returning the value in a serialization format. When you installcmakepp it will create an alias forcmake -P /path/to/cmakepp.cmake calledcmakepp.

## return content of this directory using the cmakepp.cmake file> cmake -P /path/to/cmakepp.cmake glob*.cmake --relative["cmakepp.cmake","install.cmake","package.cmake"]## perform a http GET request using the cmakepp alias> cmakepp http_get http://httpbin.org/get?key=value --json{"args":{"key":"value" },"headers":{"Accept":"*/*","Host":"httpbin.org","User-Agent":"curl/7.38.0" },"origin":"85.180.182.43","url":"http://httpbin.org/get?key=value"}## parse an uri using the cmakepp alias> cmakepp uri http+https://toeb:pass@www.example.com/path/to/file.ext?key=value&key2.subkey=value2 --select"scheme: @scheme key2.subkey: @params.key2.subkey""scheme: http+https key2.subkey: value2"

If you want to learn try or learn cmake andcmakepp you can use the interactive cmake shell by launchingcmake -P icmakepp.cmake which gives you a prompt with the all functions available incmakepp and cmake in general.

icmakepp allows you to enter valid cmake and also a more lazily you can neglect to enter the parentheses around functions e.g.cd my/path ->cd(my/path)

Since console interaction is complicated with cmake and cmake itself is not very general purpose by design the interactive cmake shell is not as user friendly as it should be. If you input an error the shell will terminate because cmake terminates. This problem might be addressed in the future (I have an idea however not the time to implement and test it)Example:

> ./icmakepp.shicmakepp> cd /usr/tobi"/usr/tobi"icmakepp> pwd"/usr/tobi"icmakepp> @echo offecho is now officmakepp> pwdicmakepp> message("${ANS}")/usr/tobiicmakepp> @echo onecho is now onicmakepp> function(myfunc name)\  # <-- backslash allows multiline input          message("hello ${name}") \          obj("{name: $name}")\          ans(person)\          return(${person})\        endfunction()"/usr/tobi"                 # <-- the last output of any function is always repeated. icmakepp> myfunc Tobihello Tobi          # <-- output in function using message{"name":"Tobi"}       # <-- json serialized return value of functionicmakepp> quiticmakepp is quitting>