Contents

Overview

Scope and Goals

One file to rule them all

Tutorial

Installation

git clone https://github.com/zeromq/gsl.gitcd gsl/srcmakemake install

git clone https://github.com/zeromq/zproject.gitcd zproject./autogen.sh./configuremakemake install

sudo make install

Getting started

Setup your project environment

<project script ="zproject.gsl">    <use project ="czmq" />    <main name ="hello" private ="1" /></project>

gsl project.xmlautogen.shconfigure.shmake

<license>    Your license disclaimer goes here!</license>

<include filename ="license.xml" />

Configuration

<!--    The project.xml generates build environments for:        autotools           GNU build system (default)        cmake               CMake build system (default)        android             Native shared library for Android        cucumber            Integration with cucumber-c        cygwin              Cygwin build system        debian              packaging for Debian        delphi              Delphi binding        docker              packaging for Docker        ios                 Native library for iOS        java                Java JNI binding        java-msvc           MSVC builds for Java JNI binding        jenkins             Jenkins pipeline build        mingw32             Mingw32 build system        nuget               Packaging for NuGet        python              Python binding        qml                 QML binding        qt                  Qt binding        redhat              Packaging for RedHat        ruby                Ruby binding        gh_actions          Github Actions configuration (same options as travis)        travis              Travis CI scripts            <option name="dist" value="trusty" /> Select a Linux distribution to use by default on Travis CI, also impacts the OBS-served repository of ZMQ-family packages to use (if not building from source all the time per use_pkg_deps_prereqs_source below). By default it would be "xenial" as of now.            <option name="distcheck" value="0" /> "0" will disable run of make distcheck in Travis CI, "2" will enable it as a special testcase allowed to fail (default: 1 to enable and require to pass)            <option name="use_pkg_deps_prereqs_source" value="0" /> "0" will disable use of use_pkg_deps_prereqs_source list in Travis CI and so cause rebuild of everything from scratch (default: 1, recently packaged prereqs must exist then)            <option name="use_cmake" value="0" /> "0" will disable use of CMake recipes in Travis CI (default: 1)            <option name="require_gitignore" value="1" /> "1" will require that the workspace is clean with regard to .gitignore settings after build (default: 0)            <option name="clangformat_allow_failures" value="0" /> "1" will generate the option allowing non-fatal failure of clang-format test in Travis CI (default: 1)            <option name="clangformat_require_good" value="0" /> "1" will generate the option allowing to report and not ignore failure of clang-format test in Travis CI (otherwise "0" hides the failure, and devs must look in test logs) (default: same as allow_failures)            <option name="clangformat_implem" value="cmake|autotools" /> will pick one of two implems of the clang-format test in Travis CI (cmake is default and faster if available, since autotools needs to configure first)            <option name="check_abi_compliance" value="0" /> "1" will compare the currently tested commit's ABI to the one in a "latest_release" branch or tag, using packaged prerequisites. Due to these limitations, the option is off by default.            <option name="check_zproject" value="0" /> "1" will regenerate the zproject of the tested commit, and will verify that nothing changed, "2" will enable it as a special testcase allowed to fail. Many projects do customize their originally generated codebase, so to avoid surprises this option is off by default.            <option name="shadow_gcc" value="0" /> "1" will enable builds with warnings configured as fatal in additional recent versions of GCC, and "2" will make failures in these cases non-fatal so you can take time to modernize your code with modern best practices in mind. This is off "0" by default.            <option name="shadow_clang" value="0" /> "1" will enable builds with warnings configured as fatal in additional recent versions of CLANG, and "2" will make failures in these cases non-fatal so you can take time to modernize your code with modern best practices in mind. This is off "0" by default.        vs2008              Microsoft Visual Studio 2008        vs2010              Microsoft Visual Studio 2010        vs2012              Microsoft Visual Studio 2012        vs2013              Microsoft Visual Studio 2013        vs2015              Microsoft Visual Studio 2015    Classes are automatically added to all build environments. Further as you    add new classes to your project you can generate skeleton header and source    files according to http://rfc.zeromq.org/spec:21.    script := The gsl script to generate all the stuff !!! DO NOT CHANGE !!!    name := The name of your project (optional)    description := A short description for your project (optional)    email := The email address where to reach you (optional)    url := The website or similar resource about the project or its ecosystem (optional)    repository := git repository holding project (optional)    unique_class_name := "0"|"1" (optional, defaults to 0) As a failsafe, forbid naming agents or classes same as the project itself (can cause conflicts in generated header filenames). Disable explicitly (set to 0) only in legacy projects that can not regenerate otherwise, and try to fix those.    license := optional common tag of the project's license ("MPLv2", "GPL-2.0+", "CompanyName Proprietary" etc.); see also license.xml for longer wording    check_license_years := "0"|"1"|"2" (optional, defaults to 0) When a project is regenerated, and if any license text(s) are defined, we check that at least one Copyright line in at least one license text contains the current year, and warn if not. If this option is set to "1", we also pause so that interactive developers can see this warning better and intervene. With "2" require that the year is mentioned, abort GSL with year if it is not.--><project script ="zproject.gsl" name ="zproject"    email ="zeromq-dev@lists.zeromq.org"    license ="MPL-2.0"    check_license_years ="0"    url ="https://github.com/zeromq/zproject"    repository ="https://github.com/zeromq/zproject"><!--        Includes are processed first, so XML in included files will be        part of the XML tree. This file can provide content of such tags        as <license> (detailed text to put in generated file headers)        and <starting_year> (a number to put in packaging copyright        summaries). Note that a verbatim "license.xml" file would be        created if it is currently missing but the tag is present, and        then it would be seeded with a current starting_year and some        boilerplate reminder to specify a real license and copyright.-->    <include filename ="license.xml" /><!--        Current version of your project.        This will be used to package your distribution-->    <version major ="1" minor ="1" patch ="0" /><!--        Current libtool ABI version of your project's shared library.        Start at 0:0:0 and see:        http://www.gnu.org/software/libtool/manual/html_node/Updating-version-info.html        for details on how/when to increment it.        If not defined 0:0:0 will be used.    <abi current = "0" revision = "0" age = "0" />--><!--        Check that the <symbol> is available after including a given <header>        and store the result in a macro HAVE_DECL_SYMBOL. When the symbol is        declared, HAVE_DECL_SYMBOL is defined to '1' otherwise '0'. Use        HAVE_DECL_SYMBOL in #if:          #if HAVE_DECL_SYMBOL            // Do something with the symbol          #endif          #if !HAVE_DECL_SYMBOL            // Alternative action without the symbol          #endif    <check_symbol_exists symbol = AI_V4MAPPED"" header = "netdb.h" />--><!--        Specify which other projects this depends on.        These projects must be known by zproject, and the list of        known projects is maintained in the zproject_known_projects.xml model.        You need not specify sub-dependencies if they are implied.        Dependencies that support the autotools build system are automatically        built by travis ci if you supply a git repository or a tarball URI.        Set type to "runtime" to have the packages install-depend on it rather        than build-depend (default type is "build").        The travis ci will use the installed packages when building instead of        rebuilding if available.    <use project = "zyre" min_major= "1" min_minor = "1" min_patch = "0" />    <use project = "czmq"        min_major= "3" min_minor = "0" min_patch = "2"        next_incompatible_major = "4"        />    <use project = "uuid" optional= "1" implied = "1" />    <use project = "myfirstlib" repository = "http://myfirstlib.org/myfirstlib.git" />    <use project = "mysecondlib" tarball = "http://mysecondlib.org/mysecondlib-1.2.3.tar.gz" />    <use project = "lua-5.1" am_lib_macro = "LUA_5_1" tarball = "..." />-->    <use project ="gsl" type ="runtime" /><!-- Header Files         name := The name the header file to include without file ending    <header name = "myproject_prelude" />--><!--        Classes, if the class header or source file doesn't exist, this will        generate a skeletons for them.        Use private = "1" for internal classes        Use selftest = "0" to not generate selftest code    <class name = "myclass">Public class description</class>    <class name = "someother" private = "1">Private class description</class>--><!--        Actors, are built using the simple actor framework from czmq. If the        actors class header or source file doesn't exist, this will generate a        skeleton for them. The generated test method of the actor will teach        you how to use them. Also have a look at the CZMQ docs to learn more        about actors.        Use selftest = "0" to not generate selftest code    <actor name = "myactor">Public actor description</actor>    <actor name = "someactor" private = "1">Private actor description</actor>--><!--        Main programs built by the project                 use private = "1" for internal tools    <main name = "progname">Exported public tool</main>    <main name = "progname" private = "1">Internal tool</main>    <main name = "progname" service = "1">Installed as system service, single-instance</main>    <main name = "progname" service = "2">Installed as system service, multi-instance (@)</main>    <main name = "progname" service = "3">Installed as system service, both single and multi-instance (@)</main>    <main name = "progname" timer = "3">Installed as system timer unit, both single and multi-instance (@)</main>    <main name = "progname" service = "1" timer = "1">Installed with both system timer and service units, single-instance - probably the former triggers the latter occasionally</main>        Note that <bin> tags for secondary distributed programs (or scripts)        now also support the service and timer attributes with same semantics.--><!--        Benchmark programs built by the project    <bench name = "benchname">Benchmark for class/function...</main>--><!--        Models that we build using GSL.        This will generate a 'make code' target to build the models.    <model name = "sockopts" />    <model name = "zgossip" />    <model name = "zgossip_msg" />        If a model should be generated using a specific gsl script,        this can be set through the script attribute:    <model name = "hydra_msg" script = "zproto_codec_java.gsl" />        Additional parameters to the script can be set via nested        param elements:    <model name = "hydra_msg" script = "zproto_codec_java.gsl">        <param name = "root_path" value = "../main" />    </model>--><!-- Other source files that we need to package    <extra name = "some_resource" />--><!-- Specify targets to build; autotools and cmake are         built in all cases.    <target name = "cmake" />    <target name = "autotools" />--><!-- Targets may be customizable with their own options-->    <target name ="cmake">        <option name ="single setting" value ="value" />        <option name ="list setting">            <item name ="item name" value ="item value" />        </option>    </target>    <target name ="obs" />    <target name ="debian" />    <target name ="redhat" /><!-- Cucumber target    <target name = "cucumber">        For each step_defs a cucumber steps runner will be registered        in the build scripts and the project's cucumber_selftest is        generated appropriately. Points the the source file        $(step_defs.name)_step_defs.c        <step_defs name = "brilliant_ideas" />    </target>--><!-- Note: zproject itself uses a customized CI-testing routine         on Travis CI, not a generated one, so DO NOT ENABLE this one:        <target name = "travis" />--><!-- Jenkins target creates jenkins pipeline         Pipeline file is not overwritten if it exists.         Your projects can build under a docker container OR agents         matched by a label OR under an "any" agent by default.         If you specify a complex label expression, be sure to use         XML escaping of the ampersand character (&amp;) if some of         your tooling expects project.xml to be valid XML (the GSL         parser accepts a verbatim ampersand character as well).         The agent_single option is a flag that enables parallel         builds of this component on several agents (specified by         label or docker) vs. a sequential build on a single agent.         Similarly, a check_sequential option can be defined so that         self-testing stages would run sequentially. This can be needed         at early stages of a project's evolution, where hard-coding is         prevalent so parallel runs in same operating environment cause         conflicts to each other. Ultimately a project should remove         this flag ;)         The build_* and test_* options influence the default setting         of corresponding build arguments for the project. You can         still run a custom Jenkins Build with Arguments with other         checkboxes clicked, e.g. while developing a missing feature.         If not explicitly set to 0, most of these options are assumed         "true", as normally a project should be capable of all these         aspects. Note however that a project with no classes marked         "stable" would by default not test non-DRAFT builds as the         configure.ac script would have no support for those anyway.         The require_gitignore option (enabled by default) also causes         the test to fail, rather than warn, if untracked or changed         files are found as a result of some build or test stage.         Also note, that after successful build and test steps, the         job generated by this Jenkinsfile can optionally trigger         some other job specific to your installation of a Jenkins         server, to handle the deployment of tested code (whichever         way you'd define that). For this optional feature, your         Jenkins master should define (and propagate to its agents)         the environment values DEFAULT_DEPLOY_BRANCH_PATTERN (regex)         and DEFAULT_DEPLOY_JOB_NAME (note to start with a slash for         absolute naming; jobs in a folder may use relative paths too).         That job should accept parameters DEPLOY_GIT_URL (URL of repo),         DEPLOY_GIT_BRANCH (name for decision-making), DEPLOY_GIT_COMMIT         (actual commit to check out and shrink-wrap into packaging.         The test_install check tries to "make DESTDIR=... install" where         the DESTDIR is test_install_DESTDIR value (must be an absolute         path), or BUILD_DIR/tmp/_inst if the option is unspecified/empty.         The test_cppcheck is different, as it calls the "cppcheck" tool         which may be not installed on a particular Jenkins deployment.         The `make cppcheck` recipe is safe to call in either case, so by         default this option is enabled if not set explicitly. Same idea         goes for build_docs as it requires asciidoc and xmlto toolkits,         except it is off by default to avoid churning CPUs with no tools.         A further dist_docs enables preparation of a "dist" tarball from         the workspace configured with docs, so you can forward it to the         publishing helper job and avoid rebuilding man pages for packaging.         Similarly, a test_check_clang_format requires an external tool,         the clang-format-5.0 (or newer) to process the codebase and decide         if it is stylish. By default the test is enabled but not required         to pass (is just informative) and will run if the tool is available         in the build system. Eventually, a project should define and uphold         its coding style -- then this test can become one of requirements         for new pull requests.         The triggers_pollSCM option sets up the pipeline-generated job         for regular polling of the original SCM repository, using the         Jenkins cron syntax. The default is approximately every 5 minutes         with a spread to minimize burst-loads vs quiet times. An explicit         empty string disables polling, so you'd only run the job manually.         Note that the most frequent working setting is "H/2", NOT a "H/1".         On the Jenkins setup used by generated projects, sometimes it was         re-scheduling the same commits over and over and even overlapping.         Usually this was linked to some lagginess of the build system or         its internet connection, but the result was a growing queue of         same (and redundant) builds. To remedy this, projects can set a         few experimental options now (and regenerate their Jenkinsfile):         * use_earlymilestone -- uses a milestone to cancel builds that            got to it later than the running one         * use_deploymilestone -- uses a milestone to cancel builds that            got to the 'deploy if appropriate' phase later than the            running one         * use_build_nonconcurrent -- sets a disableConcurrentBuilds option         * use_checkout_explicit -- sets a skipDefaultCheckout option and            defines a step to check out code explicitly; it is believed            this may better succeed in recording which commits are already            being processed by the server         The use_test_timeout option sets up the default timeout for test         steps (further configurable at run-time as a build argument).         Generally unit tests should not take pathologically long, so the         default of 30 minutes should commonly suffice even for distchecks.         If your selftests are known to take a lot of time, perhaps due to         using an occasionally overloaded Jenkins CI farm, set this option.         A use_test_retry option allows to retry each failing test step         for the specified amount of attempts; it is deemed good if the         test passes at least once. This option should not normally need         to be used -- only if selftests somehow depend on environmental         circumstances and fail occasionally but not always. Ultimately,         project developers should find and fix the issue in tests (or in         the production codebase) so it always works on the first try,         bulletproof.         As a workaround for some versions of Jenkins, if your project uses         "weird" (generally non-ASCII) filenames in the build directory,         their removal with Pipeline deleteDir() can fail even though it         should not. If this bites you, set use_deleteDir_rm_first=1 in         the project, so the OS native "rm" is tried first.         The two options do_cleanup_after_build (for parallelized tests)         and do_cleanup_after_job control whether the pipeline would by         default remove the build/test subdirectory after successful end         of stage, and/or cleans the build workspace after the whole job         succeeded, respectively. If not set, cleanup is enabled for both         and in either case the active options are among build parameters.         In opposite fashion, a do_cleanup_after_failed_build is disabled         by default to allow post-mortem inspection of errors on CI server.         You might want to keep the built sources to analyze the behavior         of your build recipes in a particular environment, thought at a         risk of using excessive disk space there. In case of failure the         workspace remains on disk to make an in-place analysis possible,         and would eat space until you clean it up manually or it would         expire according to your Jenkins old-build retention policies.    <target name = "jenkins">        <option name = "file" value = "Jenkinsfile" />        <option name = "agent_docker" value = "zeromqorg/czmq" />        <option name = "agent_label" value = "linux || macosx || bsd || solaris || posix || windows" />        <option name = "agent_single" value = "1" />        <option name = "check_sequential" value = "1" />        <option name = "triggers_pollSCM" value = "H/5 * * * *" />        <option name = "build_without_draft_api" value = "0" />        <option name = "build_with_draft_api" value = "0" />        <option name = "build_docs" value = "1" />        <option name = "dist_docs" value = "1" />        <option name = "require_gitignore" value = "0" />        <option name = "use_deleteDir_rm_first" value = "1" />        <option name = "use_test_timeout" value = "60" />        <option name = "use_test_retry" value = "3" />        <option name = "test_check" value = "0" />        <option name = "test_memcheck" value = "0" />        <option name = "test_distcheck" value = "0" />        <option name = "test_install" value = "0" />        <option name = "test_install_DESTDIR" value = "/tmp/proto-area" />        <option name = "test_cppcheck" value = "1" />        <option name = "test_check_clang_format" value = "1" />        <option name = "use_clang_format_prog" value = "clang-format-5.0" />        <option name = "require_good_clang_format" value = "0" />    </target>-->    <target name ="jenkins" >        <option name ="agent_label" value ="linux || macosx || bsd || solaris || posix || windows" />        <option name ="agent_single" value ="1" /><!-- Note: for zproject itself, all the *check jobs are             essentially a loopback to distcheck itself-->        <option name ="test_check" value ="1" />        <option name ="test_memcheck" value ="0" />        <option name ="test_distcheck" value ="0" />        <option name ="test_cppcheck" value ="0" />    </target><!-- In order loaded by zproject.gsl-->    <bin name ="zproject.gsl" />    <bin name ="zproject_projects.gsl" />    <bin name ="zproject_class_api.gsl" /><!-- Mainline generation code-->    <bin name ="zproject_skeletons.gsl" />    <bin name ="zproject_bench.gsl" />    <bin name ="zproject_class.gsl" />    <bin name ="zproject_git.gsl" />    <bin name ="zproject_valgrind.gsl" /><!-- Targets-->    <bin name ="zproject_android.gsl" />    <bin name ="zproject_autotools.gsl" />    <bin name ="zproject_cmake.gsl" />    <bin name ="zproject_cucumber.gsl" />    <bin name ="zproject_cygwin.gsl" />    <bin name ="zproject_debian.gsl" />    <bin name ="zproject_delphi.gsl" />    <bin name ="zproject_docker.gsl" />    <bin name ="zproject_gh_actions.gsl" />    <bin name ="zproject_gyp.gsl" />    <bin name ="zproject_ios.gsl" />    <bin name ="zproject_java.gsl" />    <bin name ="zproject_java_lib.gsl" />    <bin name ="zproject_java_msvc.gsl" />    <bin name ="zproject_jenkins.gsl" />    <bin name ="zproject_lua_ffi.gsl" />    <bin name ="zproject_mingw32.gsl" />    <bin name ="zproject_nodejs.gsl" />    <bin name ="zproject_nuget.gsl" />    <bin name ="zproject_obs.gsl" />    <bin name ="zproject_python.gsl" />    <bin name ="zproject_python_cffi.gsl" />    <bin name ="zproject_qml.gsl" />    <bin name ="zproject_qt.gsl" />    <bin name ="zproject_redhat.gsl" />    <bin name ="zproject_rpi.gsl" />    <bin name ="zproject_ruby.gsl" />    <bin name ="zproject_systemd.gsl" />    <bin name ="zproject_travis.gsl" />    <bin name ="zproject_vagrant.gsl" />    <bin name ="zproject_vs2008.gsl" />    <bin name ="zproject_vs20xx.gsl" />    <bin name ="zproject_vs20xx_props.gsl" />    <bin name ="zproject_known_projects.xml" /></project>

Project dependencies

<known_projects><!-- ZeroMQ Projects--><!--        Problem: naming style is inconsistent        we sometimes use libxxx and sometimes xxx; the git repo name        is unpredictable; sometimes we override with the prefix and        sometimes with libname.        Proposed solution: project name should always be git repo        name; prefix and libname should always be specified. For        compatibility, we can define aliases. E.g.:        Also, 'cmake name' is target specific and must go.        Suggested model:        <use            project = "libzmq"          required            master = "https://github.com/zeromq"                                        required            libname = "libzmq"          default = lib<prefix>            prefix = "zmq"              default = project            test = "zmq_init"           required same as AC_CHECK_LIB in autoconf            release = "<tagname>"       default = "master"            abi = "version"             default = "0:0:0"            header = "<filename>"       default = <prefix>.h            language = "C|C++"          default = "C"            optional = "1"              default = "0"            debian_name = "libzmq5-dev" default = lib<name>-dev            redhat_name = "zeromq-devel" default = <name>-devel                <add_config_opts>--with-dep1=nuance</add_config_opts>                <add_config_opts>--enable-feature2</add_config_opts>        </use>-->    <use project ="libzmq" prefix ="zmq" debian_name ="libzmq3-dev" redhat_name ="zeromq-devel" brew_name ="zeromq"        repository ="https://github.com/zeromq/libzmq.git"        test ="zmq_init" /><!-- Note: if your project requires an older CZMQ (e.g. if you need        `release = "v3.0.2"`), you may need to `test = "zctx_test"`.        Also note that you can instead require particular package        version (as reported by pkg-config records).-->    <use project ="czmq" libname ="libczmq"        repository ="https://github.com/zeromq/czmq.git"        test ="zhashx_test">        <use project ="libzmq" />    </use>    <use project ="zyre" libname ="libzyre"        repository ="https://github.com/zeromq/zyre.git"        test ="zyre_test">        <use project ="czmq" />    </use>    <use project ="malamute" libname ="libmlm"        repository ="https://github.com/zeromq/malamute.git"        header ="malamute.h"        prefix ="mlm"        test ="mlm_server_test">        <use project ="libzmq" />        <use project ="czmq" />    </use>    <use project ="gsl" libname =""        repository ="https://github.com/zeromq/gsl.git"        debian_name ="generator-scripting-language"        redhat_name ="generator-scripting-language">    </use><!-- Edgenet Projects-->    <use project ="drops" libname ="libdrops"        repository ="https://github.com/edgenet/drops.git"        test ="drops_test">        <use project ="czmq" />        <use project ="zyre" />    </use>    <use project ="hydra" libname ="libhydra"        repository ="https://github.com/edgenet/hydra.git"        test ="hydra_server_test">        <use project ="czmq" />    </use><!-- Various known third-party projects        (If you're unsure of where a project belongs, add it here)-->    <use project ="cucumber"         header ="cucumber_c.h"         test ="cucumber_new"         repository ="https://github.com/sappo/cucumber-c">        <use project ="gherkin" private ="1" />        <use project ="cJSON" private ="1" />    </use>    <use project ="gherkin"         header ="compiler.h"         repository ="https://github.com/cucumber/gherkin-c"         test ="Compiler_new" />    <use project ="cJSON"         debian_name ="libcjson-dev"         header ="cjson/cJSON.h"         repository ="https://github.com/DaveGamble/cJSON"         test ="cJSON_Parse" />    <use project ="libsodium" prefix ="sodium"        repository ="https://github.com/jedisct1/libsodium.git"        release ="stable"        test ="sodium_init" />    <use project ="libcurl"        prefix ="curl"        repository ="https://github.com/curl/curl.git"        debian_name ="libcurl4-nss-dev"        brew_name ="curl"        test ="curl_easy_init"        header ="curl/curl.h" />    <use project ="libmicrohttpd"         brew_name ="libmicrohttpd"         prefix ="microhttpd"         repository ="https://git.gnunet.org/libmicrohttpd.git"         tarball ="http://ftp.gnu.org/gnu/libmicrohttpd/libmicrohttpd-0.9.44.tar.gz"         test ="MHD_start_daemon" />    <use project ="editline"        repository ="https://github.com/troglobit/editline.git"        test ="readline" />    <use project ="fuse"        repository ="http://git.code.sf.net/p/fuse/fuse.git"        test ="fuse_main" />    <use project ="jansson"        repository ="https://github.com/akheron/jansson.git"        test ="json_object" />    <use project ="jemalloc"        repository ="https://github.com/jemalloc/jemalloc.git"        test ="malloc"        header ="jemalloc/jemalloc.h" />    <use project ="msgpack"        repository ="https://github.com/msgpack/msgpack-c.git"        test ="msgpack_version" />    <use project ="uuid"        test ="uuid_generate"        header ="uuid/uuid.h"        brew_name ="ossp-uuid"        redhat_name ="libuuid-devel"        debian_name ="uuid-dev" />    <use project ="asound"        test ="snd_asoundlib_version"        header ="alsa/asoundlib.h" />    <use project ="zdb"        repository ="https://bitbucket.org/tildeslash/libzdb.git"        test ="ConnectionPool_start" />    <use project ="json-c"        header ="json-c/json.h"        test ="json_object_to_json_string" />    <use project ="libfastjson"        repository ="https://github.com/rsyslog/libfastjson/"        header ="libfastjson/json.h"        test ="json_object_to_json_string" />    <use project ="lognorm"        repository ="https://github.com/rsyslog/liblognorm/"        test ="ln_initCtx">        <use project ="libfastjson" />    </use>    <use project ="zdiscgo"        repository ="https://github.com/zeromq/zdiscgo.git"        test ="zdiscgoplugin_new" />    <use project ="systemd"        libname ="libsystemd"        prefix ="libsystemd"        linkname ="systemd"        header ="systemd/sd-daemon.h"        test ="sd_listen_fds" />    <use project ="protobuf-c"         repository ="https://github.com/protobuf-c/protobuf-c/"         test ="protobuf_c_version"         header ="protobuf-c/protobuf-c.h"/><!-- 42ITY project https://github.com/42ity https://42ity.org-->    <use project ="fty-proto" libname ="libfty_proto"header="ftyproto.h"        repository ="https://github.com/42ity/fty-proto"        test ="fty_proto_test">        <use project ="libzmq"/>        <use project ="czmq"/>        <use project ="malamute"/>    </use><!-- OS packagers make life hard by renaming the package, binaries and         even library SONAMEs - so we have to guess a bit; note that for         practical purposes, lua-5.2 suffices as lua-5.1 (if fixes happen         to be needed, they are trivial and googlable)-->    <use project ="lua-5.1" libname ="lua"prefix="lua"        optional ="0" am_lib_macro ="LUA_5_1"        min_major ="5" min_minor ="1" min_patch ="0"debian_name="liblua5.1-0-dev"redhat_name="lua-devel"        test ="lua_close">            <linkname>lua5.2</linkname>            <linkname>lua52</linkname>            <linkname>lua5.1</linkname>            <linkname>lua51</linkname>            <linkname>lua</linkname>            <pkgconfig>lua5.2</pkgconfig>            <pkgconfig>lua52</pkgconfig>            <pkgconfig>lua5.1</pkgconfig>            <pkgconfig>lua51</pkgconfig>            <pkgconfig>lua</pkgconfig>    </use>    <use project ="lz4"        libname ="liblz4"        redhat_name ="liblz4-devel"        header ="lz4.h"        test ="LZ4_decompress_safe" />    <use project ="nss"        debian_name ="libnss3-dev"        redhat_name ="nss-devel"        header ="sechash.h"        test ="HASH_Create" /></known_projects>

Optional : Class filename configuration

<classfilename use-cxx = "true" use-cxx-gcc-4-9 = "true" pkgincludedir = "false" keep-tree = "true" pretty-print = "no" source-extension = "cpp" header-extension = "hpp" />

Targets

gsl -target:? project.xml

gsl -target:android project.xml

gsl -target:- project.xml

<target name = "android" /><target name = "java" />

<target name = "*" />

Target Options

<project    name = "..."    >    ...    <target name = "*" />    <target name = "nuget">        <option name = "id" value = "czmq_vc120" />        <option name = "dependency">            <item name = "libzmq_vc120" value = "4.2.0.0" />        </option>    </target></project>

project.nuget_id = "czmq_vc120"project.nuget_dependency.name = "libzmq_vc120"project.nuget_dependency.value = "4.2.0.0"

Android target options

<target name = "android" >    <option name = "ndk_version" value = "nnn" />    <option name = "min_sdk_version" value = "sss" /></target>

project.android_ndk_version = "nnn"project.android_min_sdk_version = "sss"

Target Scopes

Modifying generated files in an already existent project

 ################################################################################ #  THIS FILE IS 100% GENERATED BY ZPROJECT; DO NOT EDIT EXCEPT EXPERIMENTALLY  # #  Read the zproject/README.md for information about making permanent changes. # ################################################################################

~/git/zproject$ ./tstgenbld.sh> ../before.log

~/git/zproject$ ./tstgenbld.sh> ../after.log~/git/zproject$ meld ../after.log ../before.log

API models

Sample API model

<class name ="myclass"><!--        This model defines a public API for binding.        It shows a language binding developer what to expect from the API XML        files.-->    My Feature-Rich Class    <include filename ="license.xml" />    <constant name ="default port" value ="8080">registered with IANA</constant>    <constant name ="normal" value ="1" />    <constant name ="fast"   value ="2" />    <constant name ="safe"   value ="3" /><!-- Constructor is optional; default one has no arguments-->    <constructor>        Create a new myclass with the given name.        <argument name ="name" type ="string" />    </constructor><!-- Destructor is optional; default one follows standard style-->    <destructor>        Destructors implicitly get a new argument prepended, which:        * is called `self_p`        * is of this class' type        * is passed by reference        * is marked as the self pointer for the destructor (`destructor_self = "1"`)    </destructor><!-- This models an CZMQ actor. By default the actor method equals the         class name.-->    <actor>        To work with my_actor, use the CZMQ zactor API:        Create new my_actor instance.            zactor_t *actor = zactor_new (my_actor, NULL);        Destroy my_actor instance            zactor_destroy (&amp;actor);        Enable verbose logging of commands and activity:            zstr_send (actor, "VERBOSE");    </actor><!-- This models a method with no return value-->    <method name ="sleep">        Put the myclass to sleep for the given number of milliseconds.        No messages will be processed by it during this time.        <argument name ="duration" type ="integer" />    </method><!-- This models an accessor method-->    <method name ="has feature">        Return true if the myclass has the given feature.        <argument name ="feature" type ="string" />        <return type ="boolean" />    </method>    <method name ="send strings">        This does something with a series of strings (until NULL). The strings        won't be touched.        Because the next method has the same name with a prepended "v", it's        recognized as this method's `va_list` sibling (in GSL:        `method.has_va_list_sibling = "1"`). This information might be used by        the various language bindings.        <argument name ="string" type ="string" variadic ="1" />        <return type ="boolean" />    </method>    <method name ="vsend strings">        This does something with a series of strings (until NULL). The strings        won't be touched (they're declared immutable by default).        <argument name ="string" type ="string" variadic ="1" />        <return type ="boolean" />    </method><!-- Callback typedefs can be declared like methods-->    <callback_type name ="handler_fn">        <argument name ="self" type ="myclass" />        <argument name ="action" type ="string" />        <return type ="boolean" />    </callback_type><!-- Callback types can be used as method arguments-->    <method name ="add handler">        Store the given callback function for later        <argument name ="handler" type ="my_class_handler_fn" callback ="1" />    </method><!-- If singleton = "1", no class struct pointer is required.-->    <method name ="test" singleton ="1">        Self test of this class        <argument name ="verbose" type ="boolean" />    </method>    <method name ="new thing" singleton ="1" >Creates a new myclass. The caller is responsible for destroying it whenfinished with it.        <return type ="myclass" fresh ="1" />    </method>    <method name ="free" singleton ="1">        Frees a provided string, and nullify the parent pointer. Setting        `mutable = "1"` is not needed here, because transfering ownership from        the caller to the function using `by_reference = "1"` implies that it's        mutable.        <argument name ="string pointer" type ="string" by_reference ="1" />    </method>    <method name ="rotate" singleton ="1">        Rotates the characters in `data` in-place. This means that all        characters are shifted to the left by one, removing the left-most        character and appending it to the end.        <argument name ="data" type ="string" mutable ="1" />    </method><!-- These are the types we support         Not all of these are supported in all language bindings;         see each language binding's file for supported types in that         language, and add more types as needed where appropriate.         Also, see zproject_class_api.gsl to see how they're handled exactly.-->    <method name ="tutorial">        <argument name ="void pointer" type ="anything" />        <argument name ="standard int" type ="integer" />        <argument name ="default float" type ="real" />        <argument name ="standard float" type ="real" size ="4" />        <argument name ="standard double" type ="real" size ="8" />        <argument name ="standard bool" type ="boolean" />        <argument name ="fixed size unsigned integer" type ="number" size ="4">            Supported sizes are 1, 2, 4, and 8.        </argument>        <argument name ="a byte" type ="byte" />        <argument name ="conversion mode" type ="integer" />        <argument name ="char pointer to C string" type ="string" />        <argument name ="byte pointer to buffer" type ="buffer" />        <argument name ="buffer size" type ="size" />        <argument name ="file handle" type ="FILE" />        <argument name ="file size" type ="file_size" />        <argument name ="time" type ="time" />        <argument name ="format" type ="format">            This makes the function is variadic (will cause a new argument to be            added to represent the variadic arguments).        </argument>        <argument name ="variadic list argument" type ="va_list" />        <argument name ="custom pointer" type ="my custom class">            Any other type is valid, as long as there is a corresponding C            type, in this case `my_custom_class_t`.        </argument>        <return type ="nothing">void method</return>    </method>    <method name ="set foo" polymorphic ="1">      Set attribute foo to a new value. Note that this method takes a      polymorphic reference (`void *`) as its first argument, which could point      to structs of different types.      This also means that high-level bindings might give you the choice to      call this method directly on an instance, or with an explicit receiver.      <argument name ="new value"type="integer" />    </method>    <method name ="set bar">        This method takes an argument type of the (descriptive) type `foo`, but        resolving it to a corresponding C type will be skipped because it's        overridden to `foobarbaz_t` by the `c_type` attribute.        <argument name ="new foo"type="foo"c_type="foobarbaz_t" />    </method></class>

//  @warning THE FOLLOWING @INTERFACE BLOCK IS AUTO-GENERATED BY ZPROJECT!//  @warning Please edit the model at "api/myclass.api" to make changes.//  @interface//  Create a new myclass with the given name.MYPROJECT_EXPORTmyclass_t*myclass_new (constchar*name);//  Destroy the myclass.MYPROJECT_EXPORTvoidmyclass_destroy (myclass_t**self_p);//  Return true if the myclass has the given feature.MYPROJECT_EXPORTboolmyclass_has_feature (myclass_t*self,constchar*feature);//  Put the myclass to sleep for the given number of milliseconds.//  No messages will be processed by the actor during this time.MYPROJECT_EXPORTvoidmyclass_sleep (myclass_t*self,intduration);//  Self test of this classMYPROJECT_EXPORTvoidmyclass_test (boolverbose);//  @end

Supported API Model Attributes

<argument name ="socket type" type ="integer">    <map name ="PAIR" value ="ZMQ_PAIR" />    <map name ="PUB"  value ="ZMQ_PUB" />    <map name ="SUB"  value ="ZMQ_SUB" /></argument>

API Types

Tips

 # if the `method` variable is a <method/> entity:echo method.string()  # will print the model as an XML string.method.save(filename) # will save the model as an XML string to the given file.

gsl -save:1 project.xml

Generate API model from C header files

virtualenv/venv mkapisource mkapi/bin/activatepip install pycparsergit clone https://github.com/eliben/pycparser.git

mkapi.py -I /path/to/your/pycparser/utils/fake_libc_include include/czmq.h

Known caveats

Language Binding Notes

Java Language Binding

Draft API Support

<class name = "classname" state = "stable" />

<class name = "classname" state = "stable">    ...    <method name = "methodname" state = "stable">        ...    </method></class>

Removal

autotools

make uninstall

Additional files

Design goals

Example

    <main name = "MAIN">        <install type = "systemd-tmpfiles" />        <install type = "config" name = "MAIN-ldap-integration.cfg.example" />    </main>

Notes for Writing Targets

Snippets

    insert_snippet (target)

    register_snippet (target, name)

    function snippet_<target>_<name>    .macro snippet_<target>_<name>

Notes for Writing Language Targets

register_target ("somename", "Decription of target")function target_somename\.macro generate_something    ...\.endmacro    project.topdir = "someplace/somename"    directory.create (project.topdir)    generate_something ()endfunction

Schema/Architecture Overview

Informal Summary

Semantic Attributes

class.name        # string (as given in the API model)class.description # string (comment in the API model, or empty string)

method.name           # string (as given in the API model, or a default value)method.description    # string (comment in the API model, or a default value)method.singleton      # 0/1 (default: 0, but 1 for constructors/destructors)method.is_constructor # 0/1 (default: 0, but 1 for constructors)method.is_destructor  # 0/1 (default: 0, but 1 for destructors)method.has_va_list_sibling # 0/1 (default: 0)

container.name         # string (as given in the API model, or "_")container.type         # string (as given, or "nothing")container.mutable      # 0/1 (default: 0)container.by_reference # 0/1 (default: 0)container.callback     # 0/1 (default: 0)container.fresh        # 0/1 (default: 0)container.variadic     # 0/1 (default: 0)container.va_start     # string - that holds the argment name for va_start ()container.optional     # 0/1 (default: 0), up to binding generator to use

Ownership and License

Ownership and License of generated sources

Hints to Contributors

This Document