Acrobatomatic Build System - introduction and training

ABS - overview

Generic tool for software builds and deliverable package generation.

• implemented with makefiles (GNU make required) and a few shell scripts.
• C/C++, Java, python support.
• Dependency management
• Features:
• compilation, package generation,
• launch software and unit tests with or without debugger,
• source code file templates, continuous integration support, and more...

Documentation: ABS manual. .

Project files layout

Never add to revision control:

• .abs , abs-cache , local.cfg : ABS local copy and configuration
• build : workspace build output directory
• dist : deliverable packages output directory

Project configuration files:

• app.cfg : application level configuration parameters
• module.cfg : module level configuration parameters

Main configuration parameters

Application level

Module level

Main targets

Application level:

Module level:

Exercise 1 - explore sampleprj (1/2)

Checkout abs:

                        $ cd <workspace>
$ git clone https://github.com/seeduvax/AcrobatomaticBuildSystem.git --single-branch -b abs-3.1 abs-3.1
$ cd abs-3.1/sampleprj
                    

                        $ make
$ cd cpplib
$ make test
$ touch src/Example.cpp
$ make
                    

• create new directory and enter the new directory.
• create app.cfg file and set into the following configuration parameters: APPNAME , VERSION , VABS , ABS_REPO
• copy the ABS bootstrap.mk file as Makefile in the directory.
• use ABS features create modules and C++ classes and unit tests.
• Build, run and test the project.
• Build the deliverable packages.

Writing unit tests with cppunit

                            #include <cppunit/extensions/HelperMacros.h>
#include <cppunit/plugin/TestPlugIn.h>
#include "BuildScriptTester/cpplib/Example.hpp"
using namespace BuildScriptTester::cpplib;
namespace test {
class TestExample: public CppUnit::TestFixture {
CPPUNIT_TEST_SUITE( TestExample );
CPPUNIT_TEST( testCaseSuccess );
CPPUNIT_CONDITIONAL_TEST( IS_INTERACTIVE , testCaseFail );
CPPUNIT_TEST_SUITE_END();
public:
    void setUp() {
    }
    void tearDown() {
    }
    void testCaseSuccess() {
        std::cout << "in test case" << std::endl;
        CPPUNIT_ASSERT_EQUAL(1,1);
    }
    void testCaseFail() {
        CPPUNIT_ASSERT_EQUAL(0,1);
    }
};
CPPUNIT_TEST_SUITE_REGISTRATION(TestExample);
} // namespace test
                        

Good practices, tips and tricks

Test tips:

• Test requiring additional dependencies: integration tests rather than unit tests. Setup dedicated module (or even application), use T_ prefix for test only modules.
• Conditional tests: use the CPPUNIT_CONDITIONAL_TEST declaration test (not available with original cppunit), to trigger test execution on particular condition. Use it to disable test in jenkins where user inputs or specific hardware are not available.
• No file output in the module directories: all output files should go somewhere into the build directory. Use the TRDIR (build root), TTARGETDIR (module test output directory) environment variable to retrieve the right path from inside your test.

Short naming:

• Small application with a single module: give the same name to the application and module to get a short built binary name ( appname instead of appname_modname ).

Project documentation

Project documents can be managed as any source code file:

• Create a _doc module to store the documents.
• Document source files in _doc/src directory.
• set MODTYPE to doc in the _doc module configuration file.
• Write documents using the heml format (some kind of markdown/XML).
• invoke make from your _doc module to generate html and pdf files from your heml sources.

Exercise 3 - Editing HEML documents

                            $ cd <workspace>/abs-3.1/sampleprj/_doc/
$ gvim src/example1.heml
$ make
                        

                            {?set %encoding=utf-8}
{document 
  {title ...}
  {abstract ...}
{# ... #}
}
                        

                            {section %title=A section
   {section %title=A subsection
   }
}
                        

                            {fig %src=image.png %title=an image}
                        

                            {fig %src=mydiagram.png %title=UML diagram} {#
@startuml mydiagram.png
class MyClass
@enduml
#}
                        

                            1st paragraphe.
2nd paragraphe:
  - enum