zproject(part3): generate bindings

After part1(getting started) and part2(looking at generated code) now its time to generate bindings, but before that let's generate a Docker-Image that will create a docker-image with this lib installed.

Generating additional files on the project-data you can add targets. There are multiple targets to choose from:

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

Add a <target name="[target-name]"/>-tag to the project and just regenerate.

• So let's add the target-tag AND we need to specify a repository-attribute in project so the docker image knows where to pickup the source. (Afaik, for dockerimage to work you need a repositiory and there is no other way to pass the current source into it)
• We also remove the private-attribute for the starter-executable to be installed on 'make install'

<project script     = "zproject.gsl" 
         repository = "https://github.com/dertom95/zproject-tutorial.git"
         name       = "gs">
    <version major = "1" minor = "1" patch = "0" />
    <class name = "shouter"/>
    <main name = "starter" private = "1" />

    <target name="docker"/>
</project>

Regenerate:

gsl project.xml

This will generate the new docker-specific file(s):

FROM ubuntu:latest
MAINTAINER gs Developers <email@hostname.com>

RUN DEBIAN_FRONTEND=noninteractive apt-get update -y -q
RUN DEBIAN_FRONTEND=noninteractive apt-get install -y -q --force-yes build-essential git-core libtool autotools-dev autoconf automake pkg-config unzip libkrb5-dev cmake
# RUN DEBIAN_FRONTEND=noninteractive apt-get install -y -q --force-yes \

RUN useradd -d /home/zmq -m -s /bin/bash zmq
RUN echo "zmq ALL=(ALL) NOPASSWD:ALL" >> /etc/sudoers

WORKDIR /tmp
RUN git clone --quiet https://github.com/dertom95/zproject-tutorial.git gs
WORKDIR /tmp/gs
RUN ./autogen.sh 2> /dev/null
RUN ./configure --quiet --without-docs
RUN make
RUN make install
RUN ldconfig


USER zmq

Caution: Our project will generate an invalid Dockerfile due to our project not 'using' any project dependencies which seem to result in an empty 'apt-get' call in Line6. Comment this line.

To build an image with the name 'zimage' (I assume docker to be available and the current use to be in the docker-group):

docker build -t zimage .

you can run the starter-executable:

docker run zimage starter -h

if you want to see what's going on in the docker image and you want to hop into it:

docker run -it zimage /bin/bash

Generate Python-Binding

For the python-generator to work, we need to add a license file first (because the generator assumes this), but it is a good idea and we should have done this in the first place....

Let's copy an MIT-License and save it as license.xml:

<starting_year>2021</starting_year>
<license>
MIT License

Copyright (c) [2021] Zproject-Tutorial

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.
</license>

Change your project.xml like this:

<project script     = "zproject.gsl" 
         repository = "https://github.com/dertom95/zproject-tutorial.git"
         license = "MIT"
         name       = "zprotut">

    <include filename = "license.xml"/>

    <version major = "1" minor = "1" patch = "0" />
    <class name = "shouter"/>
    <main name = "starter" />

    <target name="docker"/>
    <target name="python"/>
</project>

The effect will be that newly generated files add this license on top of the file. (would have been neat to work on class-headers after(!) creation as well)

In line 4 we changed the library name from 'gs' to 'zprotut' to avoid library name clashes...(seems like there is a libgs already, my bad 😉)
In line 13 we added the python-target which will add a folder 'bindings/python'.

Due to the lib-name changed remove all file and folders with prefix gs_ and generate:

gsl project.xml

build the the library again and go to the build-folder where you can find the shared-libraries and write:

export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:$PWD

This will temporarily add this folder to the library search path and make it available for the python-binding.

cd bindings/python/
python setup.py build
python setup.py install

Notice: I'm not that confident with the best ways to manually install python-libraries. I guess you should create a virtual-environment and I guess 'python setup.py install' would have been enough...

With the shared-library in LD-Path and the python lib installed you can go on a python shell and execute following:

# import our class
from zprotut import Shouter
# create an instance. string-types need to be add as bytes with b-prefix
shouter = Shouter(b"abc")
# call the instance
shouter.shout_multi(b"forty",3)

That concludes part3 and finish the 'getting started'-guide. There is so much to explore. e.g. in the API-Model 'callbacks' or 'actors'.

Have fun with this project.