Overview

Balau is a C++ application framework designed for enterprise quality C++ software development.

Following the recent revisions of the language, C++ has matured to become an attractive candidate for rapid enterprise quality application development. Balau provides tools designed to support the rapid development of high performance C++ enterprise applications.

Balau builds on the foundations of the Boost and ICU projects, and focuses on using modern C++17 features and the standard unicode string classes.

The library has been conceived for the development of applications that have a dependency injection based architecture, have complex logging requirements, and will be developed with a test driven development methodology. Balau has also been designed to provide an application framework for Unicode aware C++ software applications.

Four key components of the Balau library are the injector, the environment configuration framework, the logging system, and the test runner. In this respect, part of Balau is a C++ equivalent to the de facto standard Java based application development components consisting of Guice/Spring for dependency injection and environment configuration, Log4j/Slf4j/Logback for logging, and JUnit/TestNG for testing.

In addition to the injector, environment configuration, logger, and test runner, Balau provides a set of components and utilities with simple APIs, including an HTTP/WebSocket web application framework.

Links

User manual (this document): https://borasoftware.com/doc/balau/latest/manual.

API documentation: https://borasoftware.com/doc/balau/latest/api.

Main Git repository: https://github.com/borasoftware/balau.

Intended audience

The following questions may be useful in order to determine if the Balau library is suitable for your requirements.

• Do you wish to develop a software application in C++ using modern best practices?
• Will the code be based on C++17 or a later specification?
• Will you be using the Boost libraries?
• Do you wish to structure your application via a dependency injection based architecture?
• Do you need to configure the application injector differently for multiple environments?
• Do you require a flexible logging system?
• Does the development team wish to use a type safe, class based, in process / out of process test framework?
• Does the development team prefer user friendly canned utilities and utility APIs?
• Do you require HTTP/WebSocket connectivity and an integrated web application framework?
• Does the development team wish to develop a recursive descent language parser in pure C++?

Themes

The main themes currently covered by the Balau library are as follows. Documentation for each component / utility may be accessed from the drop down menu at the top of this page.

• dependency injection with application and environment configuration
• Hierarchical, typed environment configuration
• Logging system, configured via environment configuration
• Test framework
• Unified to-string functions
• Unified from-string functions
• Unicode character and string utilities
• Unified resource identification and resource access
• Data structures
• Shared memory data structures
• Concurrent data structures
• Hand written language parser utilities
• Hierarchical property file format and corresponding hand written parser
• HTTP/WebSocket clients and server
• HTTP/WebSocket web application framework
• Utilities (system, compression, files, hashing, streams, strings, etc.)

Documentation pages

Developer manual

Each documentation page provided in the top menu contains documentation on the component or utility, with the following structure:

• overview;
• quick start guide;
• optional detailed documentation sections for complex components;
• an optional design discussion.

Application developers should be able to get up to speed on each component / utility by reading the overview and quick start guide. They can subsequently refer to the detailed documentation later on when more advanced use of the component / utility is required.

The Balau documentation is written in BDML, and can be loaded directly in a web browser with the included BDML XSLT stylesheet*, or translated to HTML via the BalauManual make target (xsltproc is required). An HTML translation of the documentation can also be viewed online at https://borasoftware.com/doc/balau/latest/manual.

API documentation

API documentation can be generated by running the BalauApiDoc make target (doxygen is required). The API documentation can also be viewed online at https://borasoftware.com/doc/balau/latest/api.

Dependencies

In addition to the C++17 standard library, Balau relies on two main third party libraries and three utility libraries.

The first main dependency is ICU, which provides Unicode support functions. The second main dependency is the Boost library. Boost is used for low level essential utilities and complex, low level components not found in the C++ standard library.

The three utility library dependencies are zlib, libzip and curl. The first two utility libraries provide low level compression support for the compression utilities in Balau. The third utility library provides network protocol support in the network classes.

The only other dependencies used are standard dependencies on each supported platform.

Balau includes a small number of third party utility libraries in its source code release. As these are contained within the Balau source code tree, they are not external dependencies and thus do not require linkage. These third party libraries are contained within the ThirdParty folder. As these libraries are supplied with Balau, application developers can also use them directly if required. The libraries have been namespaced within the Balau outer namespace in order to avoid potential clashes.

Application structure

The high level structure of a software application or library based on Balau is shown in the diagram below.

License

Balau is licensed under the Boost Software License Version 1.0.

Supported platforms

C++ version

Balau requires a compiler that is compliant with C++17 or a later version of the specification, with certain exceptions. Notably, guaranteed copy elision is not required (since version 2019.5.1) and boost::string_view is used as a substitute for std::string_view if std::string_view is not available.

These exceptions allow Balau to be built with the partially C++17 compliant GCC version 6.

Operating systems

Balau has been developed and tested on 64 bit Linux with the GCC and Clang compilers. A port to Windows 7/10 is planned.

Other Posix compliant platforms that are supported by Boost and ICU may work if they comply with the primitive type size assertion checks in the StdTypes.hpp header:

			static_assert(CHAR_BIT          == 8);
			static_assert(sizeof(short)     == 2);
			static_assert(sizeof(int)       == 4);
			static_assert(sizeof(long long) == 8);
		

Due to the size difference between long integers in different common data models, the long and unsigned long integer types are not used in the library other than when a dependency requires a value of one of those types. Instead, use of the long long and unsigned long long integer types allows the commonly accepted data models to be supported without primitive type size conflicts.

CPU architectures

Balau has been developed and tested on x86-64.

Concurrent code in the library uses the C++ 11 atomic operations library. Consequently, the library should be free of data races on all platforms that have a standards compliant C++17 compiler and standard library.

Building

Balau uses the CMake build system. See the building page for information on building Balau and its dependencies.

The source code includes a set of unit tests, implemented with the Balau test runner. After building the library, the tests may be run by launching the BalauTests application. The tests can also be used as an aid in getting up to speed quickly with each feature in the library.

Contributing

The core principal of the Balau core C++ library is to provide a user friendly C++ application framework on top of Boost and ICU, on which complex Unicode based C++ software applications may be created. To achieve this aim, the library contains a set of core application components (injector, environment configuration framework, logger, test runner) that form the basis of a complex C++ software application, and a set of utilities with straightforward APIs.

The library is in active development. Many of the themes can be expanded to cover a greater breadth of features and utilities.

Pull requests with additional components and utilities are welcome. Some guidelines are included on the contributing page. A current list of planned development is available on the planned features page.

Pending development

The following items are currently works in progress.

Item	Work required
Documentation	Write the WebSocket webapp framework chapter.
HttpClient/HttpsClient	Extend to use keep-alive connections.
WsWebApp	Complete design, coding, and unit test.
Log rotation	Complete design, coding, and unit testing.