Reference implementation of the MASD Code Generator.
Dogen is the reference implementation of the MASD Project code generator. MASD - Model Assisted Software Development - is a new methodology for the development of software systems based on MDE (Model Driven Engineering). MASD was developed in the context of a PhD programme; if you are that way inclined, you may find the thesis of interest: Model Assisted Software Development - a MDE-Based Software Development Methodology.
In lay terms, Dogen's objective is to automate the development process as much as possible: the user creates models using Org Mode, though these must respect a set of predefined restrictions. Dogen uses this input to generate a source code representation of the model. Unlike traditional modeling techniques like UML, Dogen focuses instead on literate modeling - an approach based on Knuth's Literate programming.
The generated code contains most of the functionality required from a typical domain object such as serialisation, hashing, streaming and so on. Whilst we intend for the application to be useful out of the box for most use cases, our end goal is to enable users to extend Dogen, adapting it to the vagaries of their specific needs. Note that Dogen has experimental C# support, but it is not in feature parity with C++ support.
Dogen provides a reference product for each supported language, available as a separate git repo:
These are intended to give you a feel for how the generated code will look like, and they attempt to exercise all of Dogen's functionality.
Our previous major milestone for Dogen was to complete the PhD thesis, which we did so successfully. The current major milestone is to sync up the source code with the latest version of the theoretical framework, as laid out in the thesis. In other words, our focus is not on producing a fully polished tool, ready for end users to deploy on industrial scale projects. If, for whatever reason you still want to go ahead and use it, bear in mind the following:
These warnings can probably best summarised as follows: "if it breaks, you get to keep the pieces; and it will break, often". But if you find such things fun, proceed with caution.
Binary packages are available for each release on and GitHub (links at the end of each release note). The binaries cover Debian Linux, OSX and Windows - 64-bit only. Packages are also generated for each commit and saved with the corresponding GitHub Workflow. Development is done from git master, so latest should always be greatest, but you may want to use packages from the previous sprint rather than what is currently under development (see badges above).
Notes
/Volumes/
, e.g.:/Volumes/dogen-${VERSION}-Darwin-x86_64/dogen.app/Contents/Resources/bin
Where ${VERSION}
is your Dogen version such as 1.0.32
.
In order to build Dogen you will need a C++ toolchain. On Linux and OSX, you'll need a recent compiler with C++ 17 support, such as GCC 11 or Clang 14 - and Ninja or GNU Make. On Windows you'll need Visual Studio 2017. On all platforms, we make use of CMake. Older compilers may work, but we try to always use the most recent releases in MASD. So, if you can, please try using to those.
Dogen has the following dependencies, across all operative systems:
Name | Type | Version |
---|---|---|
CMake | Mandatory | 3.23 or greater. |
Boost | Mandatory | 1.81 or greater. |
DTL | Mandatory | 1.19 |
Note that earlier versions may work but haven't been tested. Also, though Dogen should build fine with package manager supplied libraries - or even with hand-built dependencies - the recommended way to setup a development environment on all supported platforms is by using vcpkg, which is what this document describes. Dogen uses the "sub-module setup", whereby vcpkg is a submodule of Dogen. All of the dependencies are declared in the vcpkg.json file.
Before we proceed, please note that Dogen makes use of CMake
Presets. You
can have a look at our presets file
CMakePresets.json
for a list of available presets; alternatively, just use CMake:
$ cmake --list-presets
Available configure presets:
"linux-clang-debug" - Linux clang debug
"linux-clang-release" - Linux clang release
"linux-gcc-debug" - Linux gcc debug
"linux-gcc-release" - Linux gcc release
"windows-msvc-debug" - Windows x64 Debug
"windows-msvc-release" - Windows x64 Release
"windows-msvc-clang-cl-debug" - Windows x64 Debug
"windows-msvc-clang-cl-release" - Windows x64 Release
"macos-clang-debug" - Mac OSX Debug
"macos-clang-release" - Mac OSX Release
For the remainder of this document we shall assume linux-clang-release
,
which is our preferred preset. If it isn't yours, remember to update the preset
name to match your desired build.
To checkout Dogen, clone as follows:
git clone https://github.com/MASD-Project/dogen.git --recurse-submodules
This takes into account the vcpkg submodule setup, as well as test data (explained below). For the configure step:
cd dogen
cmake --preset linux-clang-release
You can build Dogen on all platforms (modulus preset) as follows:
cmake --build --preset linux-clang-release
If you'd like to run the project tests, execute the target run_all_tests
or its abbreviation rat
. Note that the tests check code generation against
both Dogen, as well as the reference products:
Reference products are checked out as git sub-modules under test_data
and
pointed to in the presets file, e.g.:
"environment": {
"DOGEN_PROJECTS_DIRECTORY": "${sourceDir}/projects",
"CPP_REF_IMPL_PROJECTS_DIRECTORY":"${sourceDir}/test_data/cpp_ref_impl/projects",
"CSHARP_REF_IMPL_PROJECTS_DIRECTORY":"${sourceDir}/test_data/csharp_ref_impl/Src"
},
If you see any errors running CMake - e.g. "DOGEN_PROJECTS_DIRECTORY not
found.", etc. - please make sure the sub-modules were checked out correctly.
If all has gone according to plan, you should then see that Dogen correctly
recognises the additional models (where DIR
is the top-level directory for
Dogen):
...
-- CMake Version: 3.24.2
-- DOGEN_PROJECTS_DIRECTORY=${DIR}/projects
-- CPP_REF_IMPL_PROJECTS_DIRECTORY=${DIR}/test_data/cpp_ref_impl/projects
-- CSHARP_REF_IMPL_PROJECTS_DIRECTORY=${DIR}/test_data/csharp_ref_impl/Src
...
You can run all tests as follows:
cmake --build --preset linux-clang-release --target rat
You can also use CTest to run the tests, e.g.:
ctest --preset linux-clang-release
Or, the slightly more verbose incantation which has the same result:
cmake --build --preset linux-clang-release --target test
Note that tests take slightly longer to run in the CTest incantation, and the output is a tad more verbose.
If you'd like to run Dogen to regenerate all of its models, you can do so by
using the target generate_all_org
or its abbreviation gao
. This is
useful, for example, to update the models to the latest version of Dogen, or
just to see how Dogen works. By default Dogen uses the current built version,
but you can also use another. For this you may need to tell CMake of its
location by setting CMAKE_PROGRAM_PATH
. After regeneration, you can then
use git diff
to inspect the differences produced by regeneration, if any.
The build directory contains all of the logs, under the directory log
.
Example:
cmake --build --preset linux-clang-release --target gao
Replacing linux-clang-release
with your platform and compiler.
Important: Please note that this does not regenerate the reference models.
Whilst we do not have a huge amount of documentation aimed at end users, there is plenty of assorted material discussing Dogen. Most of the material targets developers and/or researchers.
A number of videos are available discussing Dogen, gathered under "themed" playlists:
identification
model.Over time, a number of assorted blog posts have been published on Dogen, mainly covering its development process:
The release notes are also worth perusing as contain quite a lot of material about Dogen's internals.
We are strong believers in open academia so all of our papers are open.
If you have encountered a failure building Dogen or running its unit tests, please submit a bug report. It must include:
If you find a bug whilst using Dogen with one of your models, please also include:
dogen.byproducts/cli.generate.MODEL
, where MODEL
is the file name
and extension of the generated model. The log file is stored in this
directory, with a name such as cli.generate.MODEL.log
.Bugs can be submitted using github Issues.