 |
Stroika Library 3.0d24
|
|
|
Stroika Library 3.0d24
|
|
Stroika is a C++ class library. The only fully supported build environment for Stroika is GNU Make. Once you have that setup, you can build through your favorite IDE. There are other build tools required, but make auto-detects these and warns what is missing.
This build process is cross-platform. It supports cross-compiling, and builds on MacOS (XCode), Linux (via gcc, or clang) and Windows (visual studio.net). Stroika also directly supports the IDEs Visual Studio.Net, and Visual Studio code.
If you have a POSIX build environment (else see below, docker environments or installing development tools):
or
followed by:
Or, for a depending on your system, for a quicker turnaround, perhaps:
If you have a relatively standard POSIX like c++ build environement, you maybe done at this point. If you got errors, or want to know more, read on.
Some project files are pre-checked in. For example, look in Workspaces/VisualStudio.Net-2022/ or Workspaces/VisualStudio.Net-2026/ or Workspaces/VSCode/. But some files/configuration/defaults maybe needed by some of these tools so perhaps run:
to build some of them (note, if you do a make all, as suggested above, then this will be taken care of automatically).
If you are missing any components and just want a quick environment to test that has all the right build components installed, you can use the pre-built docker containers:
UNIX:
Windows:
Or - a couple other docker run variants that may help with windows
It takes a while to build all of Stroika (10-20 minutes per configuration), so adding -j10 (or so) helps a lot.
This mostly conists of the standard UNIX build tools.
Roughly:
You may find it helpful to review the instructions in Installing-Required-Tools.md which layout details per development platform.
make help
Not needed, but gives some idea of make options.
make check-prerequisite-tools
Not needed, but tells you if you are missing anything critical.
make default-configurations
Not needed, but it's a springboard for setting up the configuration you want.
Review ConfigurationFiles/Debug.xml or any of the other default configuration files
Like many non-trivial C/C++ libraries, you run configure to establish some build parameters, before invoking make. But unlike most such configuration systems, Stroika creates 'named' configurations, and facilitates building multiple such named configurations at once.
Each configuration is stored in in a file named ${CONFIGNAME}.xml in the top-level ConfigurationFiles/ directory.
./configure Debug-x86 --config-tag Windows --config-tag x86 --arch x86 --apply-default-debug-flags./configure Debug --config-tag Unix --apply-default-debug-flags./configure clang++-20-release-libstdc++ --config-tag Unix --compiler-driver clang++20 --apply-default-release-flags --stdlib libstdc++ --trace2file enableCXX=clang++ ./configure Debug-clang --config-tag Unix --apply-default-debug-flags./configure g++-valgrind-debug-SSLPurify --config-tag Unix --config-tag valgrind -valgrind enable --openssl use --openssl-extraargs purify --apply-default-debug-flags --sanitize none;Simple XML format (
Configuration files should not be edited by hand. Instead, the current command line is the first element of the configuration file: take that as a starting point and ammend it as needed, and re-run make apply-configurations or make CONFIGURATION=X apply-configuration.
The reason this is so important, is that it allows an external build system like bitbake, or node-gyp, etc to define parameters for a build, and easily generate appropriate configurations.
./Build/Scripts/GetConfigurationParameter Debug CFLAGS
-I"C:/Program Files/Microsoft Visual Studio/2022/Community/VC/Tools/MSVC/14.30.30705/ATLMFC/include" -I"C:/Program Files/Microsoft Visual Studio/2022/Community/VC/Tools/MSVC/14.30.30705/include" -I"C:/Program Files (x86)/Windows Kits/NETFXSDK/4.8/include/um" -I"C:/Program Files (x86)/Windows Kits/10/include/10.0.19041.0/ucrt" -I"C:/Program Files (x86)/Windows Kits/10/include/10.0.19041.0/shared" -I"C:/Program Files (x86)/Windows Kits/10/include/10.0.19041.0/um" -I"C:/Program Files (x86)/Windows Kits/10/include/10.0.19041.0/winrt" -I"C:/Program Files (x86)/Windows Kits/10/include/10.0.19041.0/cppwinrt" -I"C:/Sandbox/Stroika/DevRoot/Builds/Debug/ThirdPartyComponents/include/" -I"C:/Sandbox/Stroika/DevRoot/Library/Sources/" -I"C:/Sandbox/Stroika/DevRoot/IntermediateFiles/Debug/" -EHsc -nologo -GR -Gd -W4 -Zc:inline -FC -bigobj -RTCsu -GS -Oy- -Od -MTd -Z7 -D_UNICODE -DUNICODE -D_WINDOWS -D_DEBUG -DqDebug=1 -DqHasFeature_LibCurl=0 -DqHasFeature_OpenSSL=1 -DqHasFeature_WinHTTP=1 -DqHasFeature_ATLMFC=1 -DqHasFeature_Xerces=1 -DqHasFeature_ZLib=1 -DqHasFeature_sqlite=1 -DqHasFeature_LZMA=1 -DqHasFeature_boost=1 -DqStroika_Foundation_Debug_Trace_TraceToFile=1 -DqStroika_Foundation_Debug_Trace_DefaultTracingOn=1 -fsanitize=address
./Build/Scripts/GetConfigurationParameter Debug Linker
g++
./Build/Scripts/GetConfigurationParameter Release CXXFLAGS
-flto –std=c++20 -O3 -I/mnt/c/Sandbox/Stroika/DevRoot/Builds/Release/ThirdPartyComponents/include/ -I/mnt/c/Sandbox/Stroika/DevRoot/Library/Sources/ -I/mnt/c/Sandbox/Stroika/DevRoot/IntermediateFiles/Release/ -Wall -Wno-switch -Wno-sign-compare -Wno-unused-variable -Wno-unused-value -Wno-strict-aliasing -Wno-comment -Wno-unused-function -Wno-unused-but-set-variable -Wno-unused-local-typedefs -g
Stroika's build process leverages .pc (pkgconfig) files. It uses (requires) certain libraries via pkgconfig and it provides pkgconfig files for the foundation and frameworks libraries.
Builds/${CONFIGURATION}/lib/pkgconfig/stroika-platform.pc
Settings for std c++ library, sdk (e.g. windows), etc. This is used in building third-party-components to assure they reference a consistent version of std c++ etc libs
Builds/${CONFIGURATION}/lib/pkgconfig/stroika-foundation.pc
Stroika-specific pkg-config file the Stroika Foundation library. This contains defines controlling features Stroika was built with, and requires for the libraries Stroika was configured to depend upon
Builds/${CONFIGURATION}/lib/pkgconfig/stroika-frameworks.pc
Stroika-specific pkg-config file the Stroika Frameworks (UPNP, Test, WebServices, etc) library. This contains little except a requires of the stroika-foundation librar.
Stroika itself is only provided as a static library. This is because static libraries are much simpler, better for optimizing, and more flexible about configuration of the particular build options desired.
I cannot rule out ever providing a dynamic link option/feature, but I see exceedingly little point to it.
Of course, you can still use dynamic (shared library) linking however you wish for any components you build (like you can build shared libraries with Stroika), and obviously for most operatiing systems, the libraries your apps must like to are shared libraries.
But this bias towards static linking is reflected in all the defaults and samples provided with Stroika.
Stroika builds on, and neatly integrates functionality from several third-party compoenents. These components are automatically downloaded and built and integrated into Stroika (depending on configuration) or Stroika can be configured to use the system installed version of these components.
Intermediate files (objs etc) go into
Final build products (libraries and executables) go into
Build/ holds everything the build system itself needs - as distinct from the Stroika library source (Library/), the tools built with it (Tools/), the regression tests (Tests/), and the example applications (Samples/).
Its subfolders divide by role - how a file is consumed - rather than by topic. That is deliberate: the most useful thing to know about a build file is whether something executes it, includes it, or reads it as data.
| Folder | Role |
|---|---|
| Build/Scripts/ | Standalone programs, invoked directly by the Makefiles and by configure |
| Build/Lib/Make/ | .mk fragments, included by other makefiles |
| Build/Lib/Perl/ | .pl files, required by configure and by the scripts |
| Build/Shared/ | Data read at build time, rather than code |
| Build/Tools/Src/ | Source for host utilities needed before Stroika can be built |
| Build/Docker/ | Build-VM and dev container definitions |
Note that these paths are effectively public, not merely internal to Stroika: an application built against Stroika includes the makefile fragments from Build/Lib/Make/ in its own makefiles, and if it was generated by Skel it began as a copy of the templates in Build/Shared/. Renaming things here is a breaking change for applications built against Stroika.
Programs run as commands - $(StroikaRoot)Build/Scripts/PrintProgressLine ..., not bash PrintProgressLine. Consequently they must keep their executable bit; losing it breaks the build on UNIX while still appearing to work on Windows, since MSYS/Cygwin synthesize the mode.
Most are small build-plumbing helpers (GetConfigurationParameter, DetectedHostOS, PrintProgressLine, ...) - see Printing configure variables from a script. A few are meant to be run by hand:
Skel - scaffold a new Stroika-based application; see Building your own applicationFormatCode - what make format-code runs (clang-format)RegressionTests, RunLocalWSLRegressionTests, RunRemoteRegressionTests - test driversRunInDockerEnvironment - start a dev container with useful options presetLibraries pulled into other build files, and never executed - which is why, unlike Build/Scripts/, nothing here is marked executable.
Build/Lib/Make/ holds SharedMakeVariables-Default.mk (variables) and SharedBuildRules-Default.mk (rules). Include them in that order - the rules file needs variables the other defines, and warns if you get it backwards. Makefile-CMake-Common.mk adds the CMAKE_... variables used by the cmake-based third-party component builds. Makefile-Common.mk is deprecated (it just forwards to SharedMakeVariables-Default.mk).
Currently Skel-Templates/ - the application skeletons Skel copies out and substitutes into. These are kept version independent where practical: the Visual Studio project templates live in a single VisualStudio.Net/ folder, with the per-version bits (PlatformToolset, .sln version stamp) substituted in, rather than duplicated per VS release.
These two are easy to confuse:
realpath.cpp (a GNU-realpath stand-in, for MacOS) and vswhere/ (fetches Microsoft's Visual Studio locator). Compiled ad hoc by the top-level Makefile, not by the normal build.HTMLViewCompiler, which SharedBuildRules-Default.mk invokes to compile .swsp files.The dividing line is just: can it use Stroika? If yes, it belongs in the top-level Tools/. If it has to run before Stroika can be built, it belongs under Build/.
Before Stroika v3.0d24, the scripts, makefile includes and templates all lived in one top-level ScriptsLib/ folder, and the container definitions in a top-level DockerBuildContainers/. A top-level ScriptsLib/ remains, containing only deprecation shims - each entry warns and forwards to its new home - so existing application makefiles keep working. Don't reference it from new code.
On any platform, building Stroika, and all is demo applications and regression tests is as simple as cd'ing to the top-level directory, and typing make
make
Make with no arguments runs 'make help'
make help
Prints the names and details of the special targets
make all
Builds the stroika library, tests, demos, etc.
make libraries
Builds just the Stroika libraries
make samples
Builds the Stroika sample applications
make run-tests‘make CONFIGURATION=zyx run-tests REMOTE='lewis@raspberrypi’ -make CONFIGURATION=abc run-tests VALGRIND=memcheck`
Builds Stroika, and all the regression tests, and runs the regression tests. If REMOTE= is specified, the code is copied to the target machine with ssh, and the test run there (helpful for when cross-compiling). VALGRIND= is used to run memcheck, or leakcheck on the given configuration.
make project-files
Builds project files which can be used for things like visual studio (not needed)
make check-prerequisite-tools
Checks if the tools needed to build Stroika are installed and in your path. This is done automatically, and generally not needed explicitly.
make apply-configurations
To generate all the directories and files dependent on the defined configurations. Note – this is generally not necessary, and called automatically.
All the make targets (e.g. all, libraries etc) take an OPTIONAL parameter CONFIGURATION. If specified, only that configuration is built. If omitted (or empty) – ALL configurations are built.
This allows for building (or clobbering or whatever) a related family of configurations. For example
make TAGS=Windows
runs all the windows builds.
make TAGS=Unix all
runs all the UNIX compiles
make TAGS="Windows x86" all
This builds all the configurations with BOTH the Windows and x86 tag (so all the 32-bit x86 builds)
make TAGS="Unix arm" list-configurations
This doesn't build anything, but just lists all the matching configurations.
make list-configurationsmake list-configuration-tagsmake list-configurations TAGS="Windows"make list-configurations TAGS="Windows x86_64"To cross-compile for Raspberry pi,
On unubtu, sudo apt-get install g++-11-arm-linux-gnueabihf
Set cross-compiling true so that internal tests aren't run using the arm built executables.
Set –apply-default-release-flags instead of 'debug' for a smaller faster executable.
–trace2file disable to disable tracefile utility, and enabled writes a debug log to /tmp.
This builds the samples, libraries etc to Builds/raspberrypi-gcc-9)
This uses ssh to run the tests remotely on the argument machine (I setup a hostname in /etc/hosts for the mapping).
Using SSH, it's also helpful to setup ssh keys to avoid re-entering passwords
http://sshkeychain.sourceforge.net/mirrors/SSH-with-Keys-HOWTO/SSH-with-Keys-HOWTO-4.html
Visual Studio.net project and solution files are available for the Stroika demos, top-level project files, and regression tests. Once you have built your configuration files (see above), you can use the project files to build, test, extend and develop Stroika.
Stroika's build process automatically populates a property file
This contains lots of interesting stuff (used to drive intellisense etc) and is automatically included by the provided Stroika projects. And it includes two important macros (set reasonably by default, but that you may want to override):
Note users can provide their own overrides to these values in
Visual Studio Code works well with Stroika. Just open the workspace file Workspaces/VSCode/Stroika.code-workspace. The workspsace contains pre-built 'tasks' to build Stroika (run makefiles).
To use the builtin 'tasks.json' - you may need to install the VSCode extension "command variable".
Also, you will need to have tools like cygwin or MSYS (see Installing-Required-Tools.md) in your path. One good way todo this is to add to your settings.json:
The 'defaultProfile' is the one used by the tasks.json for executing commands like make all, make clean etc from vscode's build menu (SHIFT-Cntrl-B)
To some degree, this is simple, and you can just copy/munge one of the sample applications. But the paths in the makefile aren't simple to update. So Stroika provides a 'Skel' utility, that builds a skeleton application.
Use './Build/Scripts/Skel –help' to see options
CMake is gaining in popularity, and we will consider possibly moving the Stroika build system to be based on/better integrated with cmake in the future. For now, if you prefer using cmake, and want to use Stroika with cmake, see
We seriously considered a number of build systems, including cmake, ant, perl scripts, qmake, etc. They all had substantial weaknesses, with ant possibly being the best alternative, except that it's heavily java oriented. Maybe for c++ cmake would have been the best?
But just plain GNU make – appears to be a nearly universally available alternative, very standard and simple, so that's what we're doing.
But - even with just plain make, you need some sort of configure script to establish what compiler options will be defined. Again, lots of different alternatives here, but in the end I decided to just build custom scripts which build a very simple XML configuration declaration, and which drives the make process by #included 'config' makefile.
Tar failure
Errors about invalid parameters, and/or bad blocks can usually be fixed by installing a copy of gnu tar. We've tested 1.27.
cp: illegal option –
Install a copy of GNU cp
Cannot find 'blah' in Cygwin
If you are trying to install required components in Cygwin, and cannot find them in the Cygwin setup GUI, try:
cygcheck -p dos2unix
rm: cannot remove '.../boost/libs/beast/test/extern/zlib-1.2.11/contrib/dotzlib': Device or resource busy
This appears to be some weird issue with visual studio code. Quit vs code, and try again.
VisualStudio.Net project fails to load
You probably just never built, and so must run
See also STK-943
ThirdParty components not automatically rebuilt from Visual Studio project files
Due to performance reasons, and weaknesses with the Stroika makefiles, we don't automatically rebuild third party components from the project files when you say 'build'. This almost never matters. But occasionally it can cause confusion - especially getting started.
The simplest rule to remember is - build from the command line if building from the project file produces errors that sound like missing files.
/tmp/Test43: /lib/arm-linux-gnueabihf/libc.so.6: version ‘GLIBC_2.28’ not found (required by /tmp/Test43)
fix with
~~~bash make project-files ~~~
1.9.8