CLASS Project Generator

Overview

zproject - CLASS Project Generator

Contents

Overview

Tutorial

Installation

Getting started

API models

Language Binding Notes

Draft API Support

Removal

Additional files

Notes for Writing Targets

Notes for Writing Language Targets

Ownership and License

Overview

zproject is a community project, like most ZeroMQ projects, built using the C4.1 process, and licensed under MPL v2. It solves the Makefile problem really well. It is unashamedly for C, and more pointedly, for that modern C dialect we call CLASS. CLASS is the Minecraft of C: fun, easy, playful, mind-opening, and social. Read more about it hintjens#79.

zproject grew out of the work that has been done to automatically generate the build environment in CZMQ. It allows to share these automations with other projects like zyre, malamute or hydra and at the same time keep everything in sync.

Scope and Goals

zproject has these primary goals:

  • generate cross-platform build environments.
  • generate CLASS (ZeroMQ RFC/21) compliant header and source skeletons for new classes.
  • generate a public header file for your library so it can be easily included by others.
  • generate stubs for man page documentation which uses the comment based approach from CZMQ.

All you need is a project.xml file in the project's root directory which is your

One file to rule them all

At least the following build environments are currently supported:

  • Autotools
  • CMake
  • Mingw32
  • Android
  • Visual Studio

Thanks to the ZeroMQ community, you can do all the heavy lifting in C and then easily generate bindings in the following languages:

  • Delphi
  • Java (JNI)
  • Python
  • QML
  • Qt
  • Ruby

The language bindings are minimal, meant to be wrapped in a handwritten idiomatic layer later.

Tutorial

To understand step by step what zproject can do for you, read chapter 3 of @hintjens book Scalable C. Note that the book is still work in progress!

Installation

zproject uses the universal code generator called GSL to process its XML inputs and create its outputs. Before you start you'll need to install GSL (https://github.com/zeromq/gsl) on your system.

git clone https://github.com/zeromq/gsl.git
cd gsl/src
make
make install

GSL must be able to find the zproject resources on your system. Therefore you'll need to install them. The following will install the zproject files to /usr/local/bin.

git clone https://github.com/zeromq/zproject.git
cd zproject
./autogen.sh
./configure
make
make install

NB: You may need to use the sudo command when running make install to elevate your privileges, e.g.

sudo make install

NB: If you don't have superuser rights on a system you'll have to make sure zproject's gsl scripts can be found on your PATH.

Getting started

Setup your project environment

The easiest way to start is to create a minimal project.xml.

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

Once you're done you can create your project's build environment and start compiling:

gsl project.xml
autogen.sh
configure.sh
make

NB: To get a more comprehensive example copy zproject's project.xml. It contains all possible configurations and according documentation.

Licensing your project is important thus you'll need a license file. Here's an overview that might help you decide to choose a license. zproject allows you to add an appropriate disclaimer of your license as a xml file, e.g. license.xml:

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

This disclaimer can be included in your project.xml and is used whenever zproject is generating new files e.g. CLASS skeletons or bindings.

<include filename = "license.xml" />

Configuration

zproject's project.xml contains an extensive description of the available configuration: The following snippet is taken from the project.xml:

<!--
    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
        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
        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 = "[email protected]"
    license = "MPLv2"
    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 subdependencies 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 overwriten 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 amperesand character (&amp;) if some of
         your tooling expects project.xml to be valid XML (the GSL
         parser accepts a verbatim amperesand 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 hardcoding is
         prevalent so parallel runs in same operating environemnt 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 manpages 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_gyp.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

zproject's use element defines project dependencies. Model is described in zproject_known_projects.xml file:

<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"
        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"
        test = "curl_easy_init"
        header = "curl/curl.h" />

    <use project = "libmicrohttpd"
         prefix = "microhttpd"
         repository = "https://gnunet.org/git/libmicrohttpd.git"
         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"
        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

Example:

<classfilename use-cxx = "true" use-cxx-gcc-4-9 = "true" pkgincludedir = "false" keep-tree = "true" pretty-print = "no" source-extension = "cpp" header-extension = "hpp" />
  • use-cxx will force usage (or not) of c++.
  • use-cxx-gcc-4-9 will enable "use-cxx" AND enforce the use of gcc-4.9 on Travis CI for nearly complete C++11 language support that is lacking in default gcc-4.8 there.
  • keep-tree will keep the include tree structure on the install (as opposed to flat delivery of include files basenames into the single-level target directory), must be used with a conservative name format (ex: pretty-print = "no"). Currently only supported with autotool.
  • pkgincludedir option chooses whether headers of this project should be dumped into the common system includedir (legacy default), or into an includedir/projname subdirectory?. Currently only supported with autotool.
  • pretty-print define the type of class name format change in order to generate the filename. It uses the pretty-print option of gsl (see Substituting Symbols and Expressions on https://github.com/zeromq/gsl#expressions for more information).
  • source-extension define the filename extension for source files in this project.
  • header-extension define the filename extension for header files in this project.

Default value :

  • pretty-print : substitute_non_alpha_to_make_c_identifier (c option)
  • header-extension : h
  • source-extension : c (unless a cc file is present, then cc)
  • use-cxx : true if a cc file is present, false otherwhise
  • use-cxx-gcc-4-9 : false by default, older GCC versions still suffice for many C++11 features

Targets

Each target produces scripts and code for a specific build system, platform, or language binding.

To see a list of available targets:

gsl -target:? project.xml

To build a specific target:

gsl -target:android project.xml

To run zproject without building any targets:

gsl -target:- project.xml

To request specific targets in your project.xml file (autotools and cmake are automatic):

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

To request all targets in your project.xml file:

<target name = "*" />

Target Options

A target can accept options via project.xml like this:

<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>

This generates all targets (name = "*") and then configures the nuget target with options. Zproject aare provided to the target handler as:

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

Target Scopes

Each target works in its own copy of 'project'. It can therefore modify and extend 'project' as wanted, without affecting other targets.

Modifying generated files in an already existent project

You may encounter a warning in a file you want to modify like this:

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

If that happens, you need to follow these steps to make the modifications and then regenerate the code for czmq, malamute and zyre (all zeromq projects).

  1. Prior making any changes, run the script tstgenbld.sh and save its output to a log file. This will save the state of the world by regenerating several projects, building and running tests.
~/git/zproject$ ./tstgenbld.sh > ../before.log
  1. Search for a specific string from the file in the zproject files (use .)
  2. When you find it, make the modification in that file (most likely extensions will be .XML or .GSL)
  3. Then execute these steps in a Linux machine to regenerate all files for your project. This will build, install and run tests on them again, after your changes have been made.
~/git/zproject$ ./tstgenbld.sh > ../after.log
~/git/zproject$ meld ../after.log ../before.log
  1. Be aware that many files in the regenerated projects will change.
  2. This also means you will need to commit changes on zproject (your mods) and in czmq, malamute, zyre (the regenerated files with your mods). From git documentation, it seems like the command "git add -uv" could help to find out what files were actually modified from all the files that were regenerated. Supposedly this will only add the ones that were actually modified, but you should double check them. Make sure to double check even line termination (or use a comparisson tool that flags those differences). Windows specific files should have (CR+LF) termination, while Linux specific should have (LF) only termination. Best is to look for ".terminator=" examples in existing .GSL files.

API models

Using an API model zproject can generate the @interface section your class headers. Further it allows zproject to generate various language bindings on top of your CLASS project.

Sample API model

All API models are placed into the api directory which resides in the root directory of your project. For example, if your project.xml contains <class name = "myclass"/>, you could create the following api/myclass.api file:

<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 when
	finished 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>

This model will cause the following @interface to be generated inside of include/myclass.h. Note that if include/myclass.h has other handwritten content outside of the @interface section this content will be retained. If the header file does not exist zproject will create it.

//  @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_EXPORT myclass_t *
    myclass_new (const char *name);

//  Destroy the myclass.
MYPROJECT_EXPORT void
    myclass_destroy (myclass_t **self_p);

//  Return true if the myclass has the given feature.
MYPROJECT_EXPORT bool
    myclass_has_feature (myclass_t *self, const char *feature);

//  Put the myclass to sleep for the given number of milliseconds.
//  No messages will be processed by the actor during this time.
MYPROJECT_EXPORT void
    myclass_sleep (myclass_t *self, int duration);

//  Self test of this class
MYPROJECT_EXPORT void
    myclass_test (bool verbose);
//  @end

Supported API Model Attributes

The following attributes are supported for methods:

  • name - the name of the method (mandatory).
  • singleton = "1" - the method is not invoked within the context of a specific instance of an object. Use this if your method does not need to be passed a self pointer as the first argument as normal. Implicit for all constructors and destructors and for the implicit test method.

The following attributes are supported for arguments and return values:

  • type - the conceptual type or class name of the argument or return value (default: "nothing", which translates to void in C).
  • mutable = "1" - the argument or the return value can be modified. All string, format, and buffer arguments are immutable by default.
  • by_reference = "1" - ownership of the argument (and responsibility for freeing it) is transferred from the caller to the function - in practice, the implementation code should also nullify the caller's reference, though this is not enforced by the API model. If a string or buffer is passed by reference, it is also mutable by default.
  • fresh = "1" - the return value is freshly allocated, and the caller receives ownership of the object and the responsibility for destroying it. Implies mutable = "1".
  • variadic = "1" - used for representing variadic arguments.

For integer arguments you can specify one or more 'map' values, which a binding target can use to generate alternative methods. For example:

<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>

The value should be a constant that the binding code has access to.

The following attributes are supported for arguments:

  • polymorphic - indicates that the passed class instance is a sockish type. For an example see CZMQ's zsock class.

API Types

This is an incomplete list of API types:

  • "nothing" -- for return only, means "void" in C.

  • "anything" -- means "void *" in C.

  • "size" -- long size (64 bits), "size_t" in C.

  • "time" -- long time (64 bits), "time_t" in C.

  • "msecs" -- long number of msecs, "int64_t" in C.

  • "file_size" -- long file size (64 bits).

  • "boolean" -- Boolean.

  • "byte" -- single octet.

  • "char" -- single character (possibly multibyte, do we care?)

  • "integer" -- 32-bit signed integer.

  • "number" -- unsigned number, with 'size = "1|2|4|8"'.

  • "real" -- single-precision floating point with 'size = "4"' (default) or double-precision with 'size = "8"'.

  • "buffer" -- byte array. When passing a buffer argument, if the next argument has type 'size', the binding may fill the size automatically. To return a buffer, you should specify 'size' attribute that defines how to set the buffer size. This can be a constant, 'size = "ZUUID_LEN"', or a dot followed by method name in the same class, e.g. 'size = ".size"'.

  • "string" -- character array.

  • "sockish" -- a variant socket type, may be a zsock_t, libzmq void *, or an actor handle.

  • "format" -- printf format, followed by zero or more arguments.

  • "FILE", "va_list", "zmq_pollitem", "socket" -- literally that, in C. (Not sure if it is wise to use raw C types.)

  • callbacks - tbd.

  • Names of classes, e.g. zmsg.

Tips

At any time, you can examine a resolved model as an XML string with all of its children and attributes using the appropriate GSL functions:

 # 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.

You can save a snapshot of the entire resolved project model using this syntax:

gsl -save:1 project.xml

Generate API model from C header files

Writing API model for bigger project with a lot of classes can be tedious job. There mkapi.py, which automates most of the task.

In order to use it, you must install zproject itself and then pycparser. For most of real world code, you must have fake_libc_includes available too.

virtualenv/venv mkapi
source mkapi/bin/activate
pip install pycparser
git clone https://github.com/eliben/pycparser.git

Then from root directory of your project (for example czmq), type following

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

Note you must use top-level include as pycparser fails if it does not know any definition.

The tool might expect -DWITH_DRAFTS parameter if the class is not marked as a stable.

Known caveats

The tool can't distinguish methods which allocates new object. It does print a comment about adding fresh = "1" attribute to each method, which return non const pointer. However the final assigment must be done manually.

Language Binding Notes

Java Language Binding

  • Skips methods that it cannot handle properly.

  • To build, you need gradle (or equivalent). Run 'gradle build jar' in the bindings/jni directory.

  • To install, run 'gradle install'. This puts the files into $HOME/.m2/repository.

Draft API Support

zproject lets you mark classes and methods as 'draft' so that they are not installed by default in stable builds. This lets you deliver draft APIs to your users, and change them later.

By default all classes and methods are draft, unless you specify otherwise. To mark the state of a class or method, specify in the project.xml:

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

Or in the class API XML file:

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

The method will inherit the class state unless it has its own 'state' attribute.

The allowed states are:

  • draft - the class or method is not built/installed in stable releases.
  • stable - the class or method is always built and installed. A method may not be changed once marked as stable.
  • legacy - the class or method is always built and installed. It may carry a warning that support can be withdrawn at any time.

Using autotools or CMake, you can specify --with-drafts to enable draft APIs, and --without-drafts to disable them. By default, drafts are built and installed when you work in a git repository (if the directory ".git" is present), and otherwise they are not. That means, if you build from a tarball, drafts are disabled by default.

Removal

autotools

make uninstall

Additional files

Installation of third party files is a hard problem. It is not platform independent, became hard to maintain and impossible to use correctly. One of zproject's goals is a simplicity. There is a simple installation model

Design goals

  • KISS, less configuration options the better
  • no conditionals in the model, those SHALL be handled in background
  • each option solves a REAL problem, avoid extending it because you can

Example

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

systemd-tmpfiles This will add install information about systemd tmpfiles.d configuration files to autotools, packaging, and so. The resulting file /usr/lib/tmpfiles.d/MAIN.conf will be installed only if configure was called with --with-systemd-units.

config This will install additional configuration files to $(sysconfdir)/$(project.name)/$(name).

Notes for Writing Targets

Snippets

If you write a new target or extend one you might be in the situtation where you need to put code fragments into files which are not specific to your target. For example the systemd target has to extend files from the autotools, debian and redhat targets. In order to keep those files as maintainable as possible you'll include a snippet which is pull from your targets file. To include a snippet call:

    insert_snippet (target)

Where target is the identifier for the insertion point i.e. the filename. To register a snippet to be inserted simply call.

    register_snippet (target, name)

Target is must match the one in insert_snippet and the name identifies your snippet. Then you can create a function or macro with the following form (without the brackets):

    function snippet_<target>_<name>

    .macro snippet_<target>_<name>

This function will be called by the insert_snippet function. You can have an arbitrary amount of registered snippets per insertion point which will be inserted in arbitrary order so don't make any assumption on the order of the snippets per insertion point.

Notes for Writing Language Targets

This is the general form of a target:

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

  • All classes SHALL be in the project model (project.xml).
  • Each class MAY have a corresponding API model (api/{class name}.api).
  • A binding generator SHOULD consider only classes with an API model (where defined (class.api)).
  • Each API model SHALL consist of both explicit information (written in the XML file) and implicit information (inferred by the zproject_class_api script). Both kinds of information will already be resolved (and indistinguishable) when each language binding generator is invoked.
  • Each API model SHALL have exactly one class entity at the top level.
  • Each class SHALL have a name attribute.
  • Each class MAY have one or more method entities.
  • Each class MAY have one or more constructor entities.
  • Each class MAY have one or more destructor entities.
  • Each method, constructor, and destructor MAY have one or more argument entities.
  • Each method, constructor, and destructor SHALL at least one return entity, and if more than one return entity exist, only the first SHOULD be considered. The return entity MAY be ignored if it has type = "nothing" (the default when no type is given).
  • Each entity SHALL have its semantic attributes fully resolved before reaching the language binding generators.
  • Each language binding generator SHALL NOT modify values of semantic attributes of entities.
  • Each language binding generator MAY assign values to language-specific implementation attributes of entities.
  • Each language binding generator SHOULD use a unique prefix for names of language-specific implementation attributes of entities.

Informal Summary

A class is always the top-level entity in an API model, and it will be merged with the corresponding class entity defined in the project model. A class contains methods, constructors, and destructors (collectively, "method"s), and methods contain arguments and returns (collectively, "container"s). Each entity will contain both semantic attributes and language-specific implementation attributes.

Semantic Attributes

Semantic attributes describe something intrinsic about the container.

For example, arguments may be described as passed by_reference to indicate that ownership is transferred from the caller. Similarly, return values may be described as fresh to indicate that ownership is transferred to the caller, which must destroy the object when it is finished with it. It's important to remember that these attributes are primarily meant to be an abstraction that describes conceptual information, leaving the details of how code generators interpret (or ignore) each attribute up to the authors.

Semantic attributes may be implicit (not given a value in the written model). In this case, it is up to the zproject_class_api script to fully resolve default values for all attributes. Downstream code generators should never resolve or alter semantic attributes, as this could change the behavior of any code generator that is run after the errant code generator.

These are the semantic attributes for each kind of entity that will be resolved before language bindings generators are invoked:

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

The contributors are listed in AUTHORS. This project uses the MPL v2 license, see LICENSE.

zproject uses the C4.1 (Collective Code Construction Contract) process for contributions.

To report an issue, use the zproject issue tracker at github.com.

Ownership and License of generated sources

The copyright of the output of zproject is by default property of the users. The license.xml file must be set up by the users to specify a license of their choosing.

Hints to Contributors

Make sure that the project model hides all details of backend scripts. For example don't make a user enter a header file because autoconf needs it.

Do read your code after you write it and ask, "Can I make this simpler?" We do use a nice minimalist and yet readable style. Learn it, adopt it, use it.

Before opening a pull request read our contribution guidelines. Thanks!

This Document

This documentation was generated from zproject/README.txt using Gitdown

Comments
  • Problem: building projects of ZeroMQ ecosystem takes long with Travis CI

    Problem: building projects of ZeroMQ ecosystem takes long with Travis CI

    Context: With the dynamic approach of different ZeroMQ-related projects, where the Git HEAD of each dependency should always be used to take advantage of latest features (and tested against, in case of CI), there is a problem that Travis CI spends the first couple of minutes just building required dependencies, such as gsl, libzmq, czmq, etc. If project merges are fast, often the PR git branch is no longer there by the time Travis gets to trying to pull and compile it.

    Solution: When the GitHub'ed upstream/master of a zeromq ecosystem project (and optionally of projects driven by zproject) is updated and by itself has a TravisCI integration and passes the tests sucessfully, it should also produce packages in format supported by TravisCI hosts (e.g. *.deb, *.dmg - maybe using https://github.com/jordansissel/fpm for unified packaging, maybe not) and use the Travis deploy action to upload them to GitHub as a release (maybe a rolling latest release with a continuously overwritten couple of files for the package and for its source git metadata and checksums) : https://docs.travis-ci.com/user/deployment/releases

    Then the steps which git clone ... make install the upstream projects can first look for the package to be available and have same commit-id as the Git HEAD, and if a suitable package is available - just install it quickly (if any step of the check or install fails - build it locally as before).

    The purpose of this issue is to ask for common-sense review - is this a reasonable way to go? Would the ZeroMQ upstreams pick up this approach to provide such prebuilt packages of themselves so the subsequently regenerated zproject-driven projects can benefit? Is there some inherent stupidity in the plan above that would make it explode? Should I or someone else spend time implementing this? Please be constructive though :)

    Note; The links above came from https://github.com/theory/sqitch/issues/283 "Use Travis CI to create and publish packages to GitHub and/or upstream/private repositories". For DEBs they also suggested https://help.launchpad.net/Packaging/PPA hosting.

    opened by jimklimov 22
  • Problem: Cannot identify zeromq sockets by type in bindings

    Problem: Cannot identify zeromq sockets by type in bindings

    czmq uses void pointers to pass sockets. This is not necessarily the case for bindings as they might wrap zsock or zactor and pass them. IMO it is easiest to add another type named socket or zsocket to identify socket parameters in the api.

    Comments please ;-)

    opened by sappo 22
  • Problem: No convienient way to generate actor skeleton

    Problem: No convienient way to generate actor skeleton

    While working on a new project I found myself creating multiple actors. I used zproject to generate the class skeleton which worked all nicely but then I needed to manually adjust the header and source files to add the actor method startup and shutdown functionality. As actors very useful, I like to add skeleton generation for them. I would like your input on how to do this in the project.xml:

    Option 1:

    <class name = "myactor" type = "actor" private = "0|1"></class>
    

    Option 2:

    <actor name = "myactor" private = "0|1"></actor>
    
    opened by sappo 16
  • Problem: <package_dependency /> makes gsl code too complicated

    Problem: makes gsl code too complicated

    Having multiple expressions like:

    for package_dependency where 
    defined (package_dependency.for_lib) | 
    defined (package_dependency.for_test) | 
    defined (package_dependency.for_all)
    ...
    endfor
    

    in zproject_automake.gsl are making a mess out of the gsl code.

    Solution:

    opened by sappo 16
  • Problem: API need time to become stable

    Problem: API need time to become stable

    Solution: add "stability" parameter, classes/methods/constants/etc can use "draft" (default) which means they will be disabled in stable builds and hidden behind an ifdef, "stable" which means they will be enabled in all builds and will have no ifdef, and "deprecated" which for the moment is the same as "stable".

    What do you think of this solution for issue #455 ?

    Questions:

    1. Should the unstable API be enabled by default or disabled by default?
    2. Should the unstable classes headers be in the public include/ directory, or treated as private until the class is stable and generated in src/ ?
    3. Should the general project header ($PROJECT_library.h) have the #ifdefs too around the opaque typedefs and the class headers includes, or only inside the individual class headers?
    4. How to deal with individual elements inside enums? A first thought was just to loop first over the stable elements of an enum, and the over the unstable ones, but that means once an unstable becomes stable the relative positions change and the ABI is broken. Would it be acceptable if we enforce when parsing the XML that unstable elements in an enum must always go after the stable ones, and fail to generate if not?
    5. Anyone has any idea why an AC_DEFINE(ENABLE_UNSTABLE_API, 1) does not work and I have to set the define in CPPFLAGS to make it visible in the code at build time?
    opened by bluca 15
  • Problem: complicated fresh pointer handling in Ruby bindings

    Problem: complicated fresh pointer handling in Ruby bindings

    Memory of fresh strings isn't free'd automatically when FFI::Pointer goes out of scope.

    Solution: Wrap it in an FFI::AutoPointer.

    Consider the following method API:

      <method name = "encode">
          Encode a stream of bytes into an armoured string.
          <argument name = "data" type = "buffer" />
          <argument name = "data size" type = "size" />
          <return type = "string" fresh = "1" />
      </method>
    

    The corresponding C function might look like this:

      char * foo_encode(const byte * data, size_t data_size)
    

    Note that the return value is a "fresh" string, which means the caller is responsible for destroying it when finished with it. Also note that it's not a struct of the class defined in this API or any other class. It must be a C style, NULL-terminated string.

    It would be nice to have the generated Ruby bindings to automatically release said memory as soon as its corresponding FFI::Pointer goes out of scope.

    Luckily, there's FFI::AutoPointer for this. One just has to subclass it and define its .release method appropriately. This commit defines it to call libc's free(). I believe this is okay, assuming:

    • libc is available on every system
    • no project-specific function has to be used to free() a C style string

    Honestly, I'm not 100% sure if this is a good idea. Are my assumptions valid?

    Note that:

    • this applies only to functions that have char * value, which is also marked "fresh"
    • automatic release is already done in Ruby bindings for "freesh" class objects (like zmsg_t objects) (but using the class' destructor, of course)
    opened by paddor 15
  • Problem: api files cannot handle methods that require a spefic version of a library

    Problem: api files cannot handle methods that require a spefic version of a library

    An example from czmq (zsock.h):

    #if ZMQ_VERSION_MAJOR >= 4 && ZMQ_VERSION_MINOR >= 2
    
    CZMQ_EXPORT zsock_t *
        zsock_new_server_checked (const char *endpoint, const char *filename, size_t line_nbr);
    
    CZMQ_EXPORT zsock_t *
        zsock_new_client_checked (const char *endpoint, const char *filename, size_t line_nbr);
    
    #endif
    
    opened by sappo 14
  • Problem: autotools build is broken

    Problem: autotools build is broken

    Any recent PR did introduce a bug into autotools generation:

    For czmq it get

    src/Makemodule-local.am:4: *** missing separator.  Stop.
    

    And for zyre a similar

    src/Makemodule-local.am:3: *** missing separator.  Stop.
    

    @jimklimov you did a lot of changes to the autotools files today. Can you please see what's wrong!

    opened by sappo 13
  • problem : on windows, unit tests do not exit gracefully because of dl…

    problem : on windows, unit tests do not exit gracefully because of dl…

    problem : on windows, unit tests do not exit gracefully because of dll behaviour (atexit not called)

    solution : explicitly call zsys_shutdown() before exit in selftest executables

    opened by bbdb68 13
  • Problem: zproject allows to constrain only minimal version of dependency

    Problem: zproject allows to constrain only minimal version of dependency

    Solution: add support for optional maximum and next known-incompatible versions

    Verified to produce reasonable output in both configure.ac and *-pc.in files.

    opened by jimklimov 13
  • Problem:can't link with libczmq any longer

    Problem:can't link with libczmq any longer

    E.g. in malamute/malamute-core, linking main programs fails with:

    /usr/bin/ld: src/mshell.o: undefined reference to symbol 'zsys_error' /usr/bin/ld: note: 'zsys_error' is defined in DSO /usr/local/lib/libczmq.so.1 so try adding it to the linker command line /usr/local/lib/libczmq.so.1: could not read symbols: Invalid operation collect2: ld returned 1 exit status make[1]: *** [src/mshell] Error 1 make[1]: *** Waiting for unfinished jobs.... /usr/bin/ld: src/malamute.o: undefined reference to symbol 'zsys_daemonize' /usr/bin/ld: note: 'zsys_daemonize' is defined in DSO /usr/local/lib/libczmq.so.1 so try adding it to the linker command line /usr/local/lib/libczmq.so.1: could not read symbols: Invalid operation collect2: ld returned 1 exit status make[1]: *** [src/malamute] Error 1 make[1]: Leaving directory `/home/ph/work/hintjens/malamute-core' make: *** [all-recursive] Error 1

    This is new, it's been working fine so far. So I suspect some recent changes in zproject.

    opened by hintjens 13
  • Problem: Android CI build system require enhancements

    Problem: Android CI build system require enhancements

    Was 'playing' with builds/android/ci_build.sh and bindings/jni/ci_build.sh for a while, with the idea to use them by our own applications to generate ZYRE jar file for our Android application(s).

    Found them interesting, but buggy, and probably incomplete. Below, a partial list of my findings:

    1. {CZMQ,ZYRE}/builds/android/ci_build.sh: silently fail (no use of set -e). As per my investigations, may require a few other modifications, because failing when set.

    2. {CZMQ,ZYRE}/builds/android/build.sh: silently fail (no use of set -e). As per my investigations, may require a few other modifications, because failing when set.

    3. CZMQ/builds/android/ci_build.sh: clone LIBMICROHTTPD repository, instead of using the TARBALL. This already raises an error during build, but not yet seen because of 1.

    4. zproject_known_projects.xml: Show invalid repo for LIBMICROHTTPD. The given URL is wrong, so, it's probably an old version. Don't know how to fix this one, as there is no way (yet) to indicate a tarball download. Any idea is welcome.

    5. Enhancement: There is no way to rebuild ZYRE, using existing folders, to facilitate troubleshooting.

    6. zproject_*.gsl contain many places where 'android-ndk-xxx' is defined: Could be usefull to have a unique variable.

    7. Enhancement: NDK download it performed in a few places, when could be in the existing android helper file.

    8. Enhancement: HOST_PLATFORM is currently exported, but this may lead to build problems, when building dependencies. Actually, there is no reason to export it, and it should be initialized in the Android helper too.

    Additionnally:

    • found also some minor typos, here or there.
    • ZYRE Android CI build could be updated to be closer to the Zproject generated one.

    I already this to work on them, and started a 'android-build-enhancements' branch in my fork. Same branch exists in my forks LIBZMQ, CZMQ & ZYRE.

    I'll do, as usual : 1 commit for a unique solution to a unique problem, to minimize the modifications.

    opened by stephan57160 0
  • Question about Java bindings.

    Question about Java bindings.

    Following some issue with some internal project using ZProject / Java, we had to dig a bint in generated Java bindings.

    From this, it seems that generated Java bindings do not implement the fresh = "0" in <return XXX />. It looks like the returned object is always considered as fresh = "1". At least, we do not find the "owned" mechanism found with Delphi or a similar with Python.

    @bluca or @sappo, can you confirm ?

    Thx for your help.

    opened by stephan57160 3
  • Adding dependent libraries

    Adding dependent libraries

    How can one add libraries to the project?

    For example I just added an executable which depends on libdl but I can't express this in the project.xml? I now have to manually modify the generated CMakeLists.txt, or set LDFLAGS on the command line?

    Suggestions welcome!

    opened by sphaero 1
  • The _classes.h header file isn't generated for a project with only a main program

    The _classes.h header file isn't generated for a project with only a main program

    When only defining a main program without any classes:

    <main name = "demo_app">Demo App</main>
    

    Running gsl project.xml generates a demo_app.c file that has a #include "demo_classes.h" but the demo_classes.h isn't generated. Neither are the include/demo.h nor the include/demo_library.h header files generated, which means that the project dependencies are not included.

    As a workaround I define a dummy class that gets generated but isn't developed any further:

    <class name = "demo_app_dummy" selftest = "0" />
    <main name = "demo_app">Demo App</main>
    
    opened by georgeslabreche 0
  • Generated cross-compile build.sh script has syntax error when there are no dependencies

    Generated cross-compile build.sh script has syntax error when there are no dependencies

    I observed this when generating the build.sh script for a Raspberry Pi cross compilation:

    image

    $ ./build.sh 
    ./build.sh: line 107: syntax error near unexpected token `fi'
    ./build.sh: line 107: `fi'
    

    My workaround is to just comment out those lines.

    opened by georgeslabreche 2
  • Problem: python2 is EOL

    Problem: python2 is EOL

    python2 is being removed from distros, so all the packaging that uses python2-cffi is starting to be unbuildable. The packaging rules need to be independent from python2 vs python3, and each conditional on the interpreter version availability, so that we can continue to support distros like RHEL6/CentOS6 independently. For RPM is easy as OBS supports macros in spec files, but it does not support build profiles for Debian packaging. Adding it to OBS is possible but some non-trivial work.

    opened by bluca 0
Owner
The ZeroMQ project
The ZeroMQ project
Improved build system generator for CPython C, C++, Cython and Fortran extensions

scikit-build Improved build system generator for CPython C/C++/Fortran/Cython extensions. Better support is available for additional compilers, build

null 358 Sep 29, 2022
Coveralls JSON coverage generator and uploader for CMake

Coveralls Generator for CMake This is a set of CMake scripts that are meant to be used to generate and upload coverage data to http://coveralls.io/. T

Joakim Söderberg 82 Aug 8, 2022
CMake project for BL602 RISC-V processor

bl602_cmake_base CMake project for BL602 RISC-V processor How to build NOTE : This project uses a pre-compiled version of the Buffalo SDK (bl_iot_sdk)

null 9 Jan 6, 2022
Project to enable using CMake from a Maven build.

CMake-Maven-Project Introduction A Maven project for the CMake build system. It can be used by including it as a plugin within your Maven project's po

null 58 Jul 13, 2022
Enhanced CMake Project Manager plugin for Qt Creator

CMakeProjectManager2 Alternative CMake support for Qt Creator. Main differents from original CMakeProject plugin: Project file list readed from file s

Alexander Drozdov 71 May 24, 2022
A program that automatically generates CMake and Meson configuration files for your Vala project

Autovala is a program and a library designed to help in the creation of projects with Vala and CMake. It also has support for Genie.

Sergio Costas 107 Apr 7, 2021
Installation example for a C++ project (Windows) with Cmake.

CMakeInstallExample Installation example for a C++ project (Windows) with Cmake. Contents This project demonstrates how to use cmake with cpack to gen

Paul T 28 Jul 13, 2022
Example project which demonstrates various CMake features.

CMake example Example project which demonstrates various CMake features. CDash testing dashboard (probably empty but you can submit your test result t

Radovan Bast 142 Oct 1, 2022
Template for reliable, cross-platform C++ project setup using cmake.

The C++ CMake Project Template cmake-init is a sophisticated copy & paste template for modern C and C++ projects. The main goals include support of al

CG Internals 800 Sep 30, 2022
CMake module for downloading an external project's source at configure time

DownloadProject Platform Build status Linux Mac OSX Windows (VS2015) This repository contains a generalized implementation for downloading an external

Crascit Pty Ltd 430 Sep 19, 2022
This is a simple CMake tutorial project which contains some different scenarios

learning-cmake This is a simple CMake tutorial project which contains some different scenarios. hello-world: Demo a simplest CMake project. hello-worl

Bob Liu 2.8k Oct 2, 2022
This was the first ever Computer Science project that I made back in Class XII (2016). I thought I should upload it on GitHub so that it does not get lost. :)

First Ever Project This was the first ever Computer Science project that I made back in Class XII (2016). I thought I should upload it on github so th

Kshitiz Srivastava 3 Jun 7, 2021
C++20 N-dimensional Matrix class for hobby project

Ndim-Matrix C++20 N-dimensional Matrix class for hobby project Supporting matrix operations STL compatible iterators reshape (O(1) move operation, no

null 20 Jul 27, 2022
Project for C programming class building a casino that includes blackjack, slots, and scratch offs.

Casino Project for C programming class building a casino that includes blackjack, slots, and scratch offs. Project description This project will requi

Jules Guasp 1 Nov 4, 2021
2nd Semester C Language Project-Cricket Score Generator

Semester-2-Project 2nd Semester C Language Project-Cricket Score Generator TITLE: Cricket Score Generator Objectives: To generate the score card for a

null 1 Jan 9, 2022
libsequence: a C++ class library for evolutionary genetic analysis

libsequence2 is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 3 of the License, or (at your option) any later version.

Kevin R. Thornton 49 Apr 30, 2022
free C++ class library of cryptographic schemes

Crypto++: free C++ Class Library of Cryptographic Schemes Version 8.4 - TBD Crypto++ Library is a free C++ class library of cryptographic schemes. Cu

null 3.6k Sep 26, 2022
A simple C++ 03/11/etc timer class for ~microsecond-precision cross-platform benchmarking. The implementation is as limited and as simple as possible to create the lowest amount of overhead.

plf_nanotimer A simple C++ 03/11/etc timer class for ~microsecond-precision cross-platform benchmarking. The implementation is as limited and simple a

Matt Bentley 98 Sep 28, 2022
A simple class for parsing JSON data into a QVariant hierarchy and vice versa.

The qt-json project is a simple collection of functions for parsing and serializing JSON data to and from QVariant hierarchies. NOTE: Qt5 introduced a

null 301 Sep 22, 2022
Class containing Anti-RE, Anti-Debug and Anti-Hook methods. Made for C++/CLI

Umium Class containing Anti-RE, Anti-Debug and Anti-Hook methods. Easy to use and easy to implement. Disclaimer This code has been made and optimized

null 42 Sep 10, 2022