GitHub repo's master branch at a glance:
Hi, and welcome.
This is a repository for experiments, mainly with C++ components.
Although you'll find usable utilities here, keep in mind that most things are proofs of concept, and are not of production quality.
In particular, for most components, I'm the only author, and didn't benefit from any external review, which is crucial for quality.
That being said, the components range from cryptography (MD5, SHA-1, SHA-2) to checksums, string utilities, operating system identification and much more. You'll get a precise idea by exploring the breeze/ subdirectory of the source tree or the full documentation (see below).
All these experiments have been developed, in my spare time, over a period of about 15 years (as of June 2021). Some experiments just didn't pan out, so, in fact, I'm not using those parts as they are here. Also, some components don't take full advantage of the latest standards and some are or will be superseded by standard components or features. But, generally, the library is up to date with C++17.
NOTE: it's possible that I'll archive this repository, or make it private, and publish a new repository with updated components, instead. So, working on it to submit e.g. a pull request might not be a good idea. OTOH, you might found a defect which still exists in the definitive version of a component, so, feel free to contact me for issues (see below).
Building the library
Breeze has been designed and implemented to be as portable as possible, without a single usage of #if, #ifdef or #ifndef (the only conditional compilation is for include guards), and the goal is that it can be compiled with any conforming C++17 compiler.
The provided build system, however, requires a Unix toolkit, with Python 3 and GNU Make. On Microsoft Windows, you'll need Cygwin. (Historically, I used awk and other Unix tools for things that I'd now do in Python; long term, I'll completely migrate to Python, but, for the moment, we need those tools, as as well.)
Note that only Cygwin 64-bit is supported.
For the editor support, and for some tests, you need to define the environment variable BREEZE_ROOT to the full path of the source tree. Use forward slashes, even on Windows, and omit the trailing slash.
The bin/ subdirectory of the Cygwin installation must be in the PATH.
To build the library:
if you are on Windows and you want to use MSVC, run a Visual Studio Command Prompt and, from there, either Cygwin's Bash (usually C:\cygwin64\bin\bash.exe) or mintty (usually C:\cygwin64\bin\mintty.exe); of course, if you launch mintty, use its window for the following steps
cd to $BREEZE_ROOT (add quotes if the value of $BREEZE_ROOT contains spaces)
issue a command like this:
architecture=x86_64 system=windows compiler=gcc build_type=optimized make
Note: on some systems, you might need to use gmake instead of make.
The architecture part can be omitted for x86_64 (that's the default).
The clean target is also supported (you still need to provide system, compiler and build_type: when you clean, only the files generated for a given architecture/system/compiler triplet and build type (debug/optimized) are removed).
At the moment, system must be set to one of the following:
- unix, windows, macos
while compiler must be set to one of:
- clang, gcc, msvc
The value unix should work on all Linuxes and FreeBSD, while macOS needs its own value.
Finally, architecture can be anything, because it is currently only used to include or exclude a component (get_cpuid_info()) which is specific to x86 and x86_64; and build_type must be one of:
- debug, optimized
Under Cygwin, with both Clang and GCC, you can build with system=windows or system=unix. In both cases, this will, by default, generate a library which depends on the Cygwin DLL. To avoid this dependency when system=windows, you can use the compilers provided by the mingw*gcc* or mingw*clang packages (available in the Cygwin installer) and select one of them via the compiler_command variable; e.g.:
system=windows compiler=gcc build_type=optimized compiler_command=x86_64-w64-mingw32-g++ make
Warning: you might want to also add
cpp_extra_options="-static -static-libgcc -static-libstdc++"
to the command line, but note that the cpp_extra_options variable is experimental.
Note: to get a list of the available Make targets, with a brief description for each of them, launch the command ``make help`` (or ``gmake help``).
Building the documentation
The documentation is contained in the source files, in the form of Doxygen comments. In fact, that's doing things backward, because it's the declarations that should be generated from the documentation. But is there a tool to do that? If you know of one, please let me know.
In the meantime, I'm using Doxygen, Breathe and Sphinx. I started by using Doxygen alone, but it is very buggy and its HTML output is awful both structurally and aesthetically. I tried to at least make the output less kitsch, by fiddling a bit with an additional CSS and a layout file, but the result was still poor. To the point that I unwillingly used to recommend to mostly read the documentation directly from the source files. At some point, I discovered DocsForge, which was an improvement, but still inadequate.
So, there was a long research of an alternative tool. The best of the suitable alternatives (as of September 2021) seemed to be Sphinx. It takes reStructuredText as input, but has an extension, called Breathe, which can generate reStructeredText from XML, so I settled on using Doxygen to generate XML, transforming it with Breathe and feeding the result to Sphinx. There are still glitches here and here (which, I suspect, are still due to Doxygen), but, overall, we seem to be on the right track.
I guess the final move should be generating the XML with a different extractor and get rid of Doxygen altogether. I'll continue my research.
To generate the documentation, move to the root of the working tree, then run:
You'll need to install Doxygen, Breathe and Sphinx (of course), and the Read the Docs Sphinx theme (or configure Sphinx to use a different theme). For the latter three, these commands will do the trick:
pip3 install sphinx pip3 install breathe pip3 install sphinx-rtd-theme
I suspect you'll need the exact Doxygen version that was configured, because I noticed that, when upgrading, Doxygen makes some breaking changes. You can check what the version is at the top of doxygen.cfg.
The source tree contains a .editorconfig (https://editorconfig.org). In addition, files having name extensions that are not automatically recognized by Emacs or Vim (e.g. .tpp) have simple trailers which make these editors recognize the file type.
If you plan to contribute, please use tool/init_file/init_file.py to initialize your source files. You should define the environment variable BREEZE_CONTRIBUTOR to the name you wish to appear in your copyright notices.
If you use Vim, just source breeze.vim from your .vimrc and that will take care of running the initialization script on any file you create in BREEZE_ROOT or in any subdirectory.
If you use another editor, please contribute something analogous to breeze.vim for that editor.
Git commit message template
To enable the Git commit message template provided with the library:
cd to BREEZE_ROOT
git config --local commit.template ./.git_commit_message_template.txt
For better or for worse, the library uses the Git commit message guidelines outlined at https://chris.beams.io/posts/git-commit/, except that the subject line:
- can reach 72 characters, just like the body lines (50 is really too little)
- is worded in the imperative mood, but doesn't necessarily complete the sentence "this commit will..."; e.g. it may begin with "Don't" (I believe that, in fact, this is the intent of the guidelines)
Please, have a look at the guidelines if you are not familiar with them.
Note that, as of August 24, 2020, if you need to use the library with MSVC 2015, that's quite easy as long as you are willing to give up on constexpr for some components (BREEZE_ASSERT(), count_bits() (now population_count()), gcd(), lcm()).
|Compiler||Minimum supported version|
We will soon add facilities for handling command line options.
Breeze is made available subject to the terms of the 3-Clause BSD License, reproduced in the file 3_CLAUSE_BSD_LICENSE.txt, at the root of the source tree.
I can't guarantee any kind of support, but if you have an issue with the library, please send me a mail describing the problem (email@example.com) and I will try to address it as soon as possible.
My most heartfelt thank you goes to James Kanze, without whom I wouldn't be the programmer I am.