For those of you that don't know, as I never actually announced the project here,
I'm working on a microframework to develop web applications in C since 2013.
It is called balde, and I consider its code ready
for a formal release now, despite not having all the features I planned for
it. Unfortunately its documentation is not good
I don't work on it for quite some time, then I don't remember how everything
works, and can't write proper documentation. To make this easier, I'm starting
a series of posts here in this blog, describing the internals of the framework
and the design decisions I made when creating it, so I can remember how it
works gradually. Hopefully in the end of the series I'll be able to integrate
the posts with the official documentation of the project and release it! \o/
Before the release, users willing to try balde must install it manually from
Github or using my Gentoo overlay (package is called
net-libs/balde there). The previously released versions are very old and
deprecated at this point.
So, I'll start talking about the foundations of the framework. It is based on
GLib, that is the base library used by
Gtk+ and GNOME applications. balde uses it as an utility library, without
implementing classes or relying on advanced features of the library. That's
because I plan to migrate away from GLib in the future, reimplementing the
required functionality in a BSD-licensed library. I have a list of functions
that must be implemented to achieve this objective in the
this is not something with high priority for now.
Another important foundation of the framework is the template engine. Instead
of parsing templates in runtime, balde will parse templates in build time,
generating C code, that is compiled into the application binary. The template
engine is based on a recursive-descent parser, built with a parsing expression
grammar. The grammar is simple enough to be easily extended, and implements
most of the features needed by a basic template engine. The template engine
is implemented as a binary, that reads the templates and generates the C source
files. It is called
balde-template-gen and will be the subject of a
dedicated post in this series.
A notable deficiency of the template engine is the lack of iterators, like
while loops. This is a side effect of another basic characteristic
of balde: all the data parsed from requests and sent to responses is stored as
string into the internal structures, and all the public interfaces follow the
same principle. That means that the current architecture does not allow passing
a list of items to a template. And that also means that the users must handle
type conversions from and to strings, as needed by their applications.
Static files are also converted to C code and compiled into the application
binary, but here balde just relies on GLib GResource infrastructure. This is
something that should be reworked in the future too. Integrate templates and
static resources, implementing a concept of themes, is something that I want
to do as soon as possible.
To make it easier for newcomers to get started with balde, it comes with a
binary that can create a skeleton project using GNU Autotools, and with basic
unit test infrastructure. The binary is called
balde-quickstart and will be
the subject of a dedicated post here as well.
That's all for now.
In the next post I'll talk about how URL routing works.
While users may be able to use
blogc as is with the help of generic tools,
some of these tools are really boring to setup.
With that in mind, I'm trying to develop some simple tools to help the users
getting their blogs online. At this point I have two tools ready for usage:
Packages are available for Gentoo, and in my Copr
blogc-git-receiver is a login shell and a git pre-receive hook, that
can create git repositories and build/deploy your websites automatically.
Users just need to create an user, configure it to use
blogc-git-receiver as its login shell, then every time that some
authorized user pushes to a repository it will create a local bare
repository in the server, if needed, and if the push includes some change to
the master branch, it will rebuild your website for you.
blogc-git-receiver tries to be as atomic as possible, building the new
version of the website in a separate directory, and using a symlink to point
to the most recent version of the website, removing the old version only
after a successful new build.
blogc-git-receiver creates a symlink inside the bare git repository,
htdocs, that points to the last successful build. Users just need
to make their webservers use this symlink as document root for their virtual
host, and make sure that the webserver can follow symlinks.
With this tool, users can create their own PaaS-like environment, using a
cheap VPS to host lots
of blogs. ;-)
This tool is one of the reasons why I wanted to make
blogc as fast as
possible, because it will rebuild all the website every time, not just the
changes, for the sake of consistency.
This tool is also a good sample code for people interested in understand how
a login shell and a git hook works.
Gentoo package is
dev-vcs/blogc-git-receiver and RHEL/CentOS/Fedora
Some simple documentation is available at:
blogc-runserver is a simple HTTP server, that comes with several rules
pre-defined, that tries to mimic the way most production servers work when
serving static websites. Users just need to point
blogc-runserver to the
output directory where
blogc created its result files.
Makefile rule is able to run your website for testing:
Yeah, it is really that simple! :)
Please keep in mind that this server should not be used in production. It is
really simple, and developed for testing purposes.
Gentoo package is
www-servers/blogc-runserver and RHEL/CentOS/Fedora
Some simple documentation is available at:
I have more ideas of new tools, that I will probably explain in future posts,
but if you have ideas of useful tools, please let me know.
So, this is a follow-up for my previous post, about my
I promissed to write something about the "new blogging engine" that runs it,
and my plan was to finish some documentation and release a first "stable"
version of the project before writing this post. And surprisingly it is
After a few beta versions, mainly to verify build system and packaging, I
released the first "stable" version a few days ago, with some simple
documentation (man pages) and all the features required for basic usage.
This blog is powered by blogc, that is a blog compiler.
It works like an usual source code compiler, converting input files written
in a custom input language into a target file, based on a template. It can
generate almost any resource file needed by a website/blog as target file,
depending on the template used, like posts, pages, feeds, sitemaps, etc.
Hmm, but this isn't similar to what [put your favorite static site generator here] does?!
Yeah, it is, indeed. But blogc was developed to be:
- Stateless and idempotent: no global state is shared by the binary between
compiler calls, and compiler calls with the same arguments should always
generate the same output. The compiler should not need to manage what
needs to be rebuilt or not, this is a job for a build tool like
- Fast: the compiler should be able to generate a complex target file in a
few miliseconds, making it easy to regenerate the full website/blog
whenever needed. This is a feature required by another component of this
project, that I'll introduce in another post.
- Simple: Both the source and template syntaxes are simple enough to be
learned quickly, and are specific for this use case.
- Easy to host: it produces static files, that can be hosted anywhere.
And why create another blog-related project?!
As most of the people who read this blog knows, I like to research and
implement stuff related to personal content publishing, despite not being a
frequent blogger. This time I wanted to put in practice some concepts I had in
mind for some time, and play with handwritten parsers.
This project is built around 3 parsers, that are basically state machines.
The parsers are heavily inspired by nodejs' http parser, that is inspired by
nginx's http-parser. This
"methodology" of building parsers make it easy to create fast and memory
blogc is totally implemented in C99, without any external dependencies.
blogc comes with a somewhat complete unit test suite, that depends on
cmocka. Obviously, users who don't want to run the test
suite don't need to install cmocka.
I'll provide more implementation details in a future post.
OK, how can I install it?! :D
Gentoo users can install blogc from the main package tree. Please note that
the package is keyworded for
# emerge -av app-text/blogc
Fedora users, and users of other Linux distributions that support the
EPEL repository, can install it from my
After enabling this repository, just type:
# yum install blogc
I have plans to package it for Ubuntu/Debian, but this is low priority right
Users without access to prebuilt packages can install blogc from source. Just
visit https://blogc.rgm.io, download a source tarball, extract it and build.
It is an autotools project, that builds with the usual command combo:
# make install
And how can I get started with blogc?
The website contains lots of useful information.
With blogc installed, you can read man pages:
are also available in the website.
You can also use our example website as base for your own website. It
is very simple, but should be a good start point:
$ git clone https://github.com/blogc/blogc-example.git my-blog
$ cd my-blog
$ rm -rf .git
$ git init .
$ git add .
$ git commit -m 'My new blog, initialized from blogc-example'
The example website uses a Makefile to build the website. Reading this
Makefile is a good way to learn about how blogc works. This Makefile just
works with GNU Make, but users should be able to write a Makefile that works
with any Make implemantation that follows POSIX standards, if wanted. Users
can also use task runners like Grunt, if they know how to make it call blogc
What the name "blogc" means?
"blogc" stands for "blog compiler". The name has nothing to do with the
programming language used to implement it. ;-)
And what about blohg? It was abandoned?
I'm still maintaining it, and it seems to be stable enough for general usage
at this point. Feel free to contact me if you find some bug on it.
That's it for now.
I hope you like blogc!
I'm starting a new blog!
Actually, it is almost the same blog, but powered by a new "blogging engine",
and I don't want to spend time migrating the old posts, that are mostly
outdated right now.
The old content is archived here, if you need it due to some crazy reason:
For Gentoo planet readers, everything should be working just fine. I created
rewrite rules to keep the old atom feeds working.
I'll publish another blog post soon, talking about the "blogging engine" and
my next plans.