DokMelody design notes

⦿ docs

In the docs page I added the DokMelody IDE design notes, and my internal scratchpad development notes.

The project is crazy because there are too many things to do for a one-man project. But it is my pet project: I like day-dreaming about it, and reading interesting papers. I will start soon the development of a prototype. Obviously I don’t expect to implement all the things described in documentation.


⦿ decision-record

1  Status


  • REPLACE DR–0003-LGPL-license

2  Context

In Dok, libraries can be managed like templates, i.e. specialized and then injected inside the code of the combined-work.
If these libraries are under a “viral license” like GPL and LGPL then also the derived work will be affected because the code of these libraries is not anymore distinct from the derived work, but it became part of it.

3  Decision

The permissive license Boost Software License v1.0 (BSL) will be used, because:
  • the library code can be injected inside derived work code without affecting its license

  • it is the license of C++ STL Boost libraries, that are used in a lot of projects with different licenses, using a compilation process similar to Dok

  • the derived works binary distributions are not obliged to credit the used libraries, so it is less stringent than MIT and BSD licenses

  • it is an OSI approved license

  • it is short and simple to read

Despite being released under BSL, Dok can (re)use the source code of other libraries released under many different licenses. So Dok MUST include a licensing management tool for analyzing the libraries usend in each distinct project and inferring:
  • the final license of the derived work

  • if the derived work MUST be relinkable with newer versions of used LGPL libraries

  • the credits to give to used libraries in source-code and in binary distribution

  • other licensing aspects

DokMelody documentation that is not part of the source code will be released under CC-BY–4.0. It is a well known license, good for documentation material, used from many big projects like Wikipedia.

3.1  Boost Software License 1.0 text

Boost Software License - Version 1.0 - August 17th, 2003
Permission is hereby granted, free of charge, to any person or organization obtaining a copy of the software and accompanying documentation covered by this license (the “Software”) to use, reproduce, display, distribute, execute, and transmit the Software, and to prepare derivative works of the Software, and to permit third-parties to whom the Software is furnished to do so, all subject to the following:
The copyright notices in the Software and this entire statement, including the above license grant, this restriction and the following disclaimer, must be included in all copies of the Software, in whole or in part, and all derivative works of the Software, unless such copies or derivative works are solely in the form of machine-executable object code generated by a source language processor.

3.2  How to apply the license

Every (also minor) source code file must start with an header comment like

SPDX-License-Identifier: BSL–1.0
Copyright (C) 2019 Author Name <>
Authors and contributors must add them self to the list of copyright holders, when they change a file.
Contributors of minor bug-fixes and minor patches can also not add them self to the list of copyright owners of the file. In this case the project repository history will give them credit.
Some source files can contain source-code under different licenses. They will use the proper SPDX identifier.
Ownership of source files is distributed between all contributors.

3.3  Problems with LGPLv3+

LGPLv3+ license was previously considered but discarded.
LGPLv3+ enforces a very nice and fair “right to repair”, i.e. the user of a product X using a LGPL library L MUST be able to create a new version of X using a different/improved/patched version of library L.
But LGPLv3+ can not be called from GPLv2 code bases, and there are many interesting projects using GPLv2 instead of GPLv2+. So there is some fragmentation problem for (L)GPL-like licenses.
Worse using LGPLv3+ in DokMelody IDE tools, there can be annoying complications because DokMelody IDE will transform the source code injecting some LGPLv3+ source code, then:
  • or the original version of the source code MUST be maintained, for allowing a transformation with a new version of the LGPLv3+ library, despite the injected code is usually very trivial

  • or the source code must be released under GPLv3+ license

GPL and LGPL with a static linking exception and other similar exceptions can be right in Dok/DokMelody but they make more difficult reusing code from other plain GPL and LGPL projects because they are not compatible together.
So despite LGPLv3+ philosophy is very fair and reasonable, its usage in practice can introduce annoying problems.

Resource management

⦿ docs

Exceptions and resource management are important aspects for creating robust systems, because in production unexpected problems can happen and because not immediately released resources can halt a system due to excessive leaking. It is not unusual having a 30% or more of production code devoted to managing these aspects.

Initially I designed exception handling and resource management in the traditional way, with try { .. } catch { .. } finally { .. } code bloks. But then I figured out that resource management is often boiler-plate code, and exception handling code is not very structured because only already open resources can be released, and the repair depends from the point of interruption. So Dok supports resource management (particular in presence of exceptions) favouring metaprogramming compiler rules injecting a default behaviour in code written without explicit resource management.

Exceptions are managed:

  • case A) fixing the problem and re-running the same code, in the Eiffel way
  • case B) signaling the problem to the parent caller, in a traditional way, but inspired also by Erlang approaches

Dok programming language

⦿ docs

This is an initial, incomplete and embarrassing draft of Dok programming language design: /dok-lang/Dok.html.

I have many things to integrate in the language, but the real test-bed will be:

  • the creation of Dok compiler in Dok itself
  • the creation of DokMelody IDE in Dok itself


⦿ plan

DokMelody aims to be:

  • an environment for analyzing and transforming knowledge
  • an IDE for programming in various programming languages
  • a distributed network of shared documents
  • a collaborating community of users and content creators
  • a channel for funding content creators

DokMelody will be implemented in Dok, that is the new DokMelody related programming language for analyzing and transforming hierarchical (tree-like) data, and in Knil that is another new language for managing relational and graph-like data.

DokMelody and related projects will be bootstrapped using the Racket programming language.

This website will be a journal for this probably unrealistinc and too much ambitous project.


⦿ decision-record

1  Context

DokMelody requires a lot of decisions on how structure the project and the eventual community.

2  Decision

Decisions will be documented and recorded inside Decision Records (DR), following an approach similar to Architecture Decision Records.
Various methods can be followed for taking and recording decisions:

3  Consequences

  • decisions and their rationale will be documented

  • more focused view of the project

  • none


⦿ decision-record

1  Status

  • DISCARDED in favour of DR–0004-Boost-license

2  Context

DokMelody is a project composed of an user interface, various programming languages compilers, and libraries.
The IDE can use different widgets and components, and it can run on different end-user systems.
In Dok many libraries are managed like templates: they are transformed/specialized and then injected inside the code of the combined-work, and they are not anymore shipped as distinct libraries.
DokMelody can be used for producing commercial and propietary code, and not only OSS software.
The metaprogramming nature of DokMelody favours the import and reuse of a lot of code of different projects, under different licenses.

3  Decision

DokMelody code for user interface, compilers and libraries will be licensed under the LGPLv3+ license, following the spirit of Collective Code Construction Contract (C4) (i.e. “The copyrights in the project SHALL be owned collectively by all its Contributors”).
Patches to external projects and libraries used from DokMelody will be released using the original upstream license, for avoiding unucessary forks.
Documentation that is not part of the source code will be released under CC-BY–4.0 for maximizing reuse.
DokMelody will include a tool for checking the license of used libraries and components, and suggesting the legal implications for the license of the combined-work.

4  Consequences

4.1  Short story

The majority of Dok applications can use commercial licenses but they had to be released with some (obfuscated) source-code, for allowing the rebuild/relink with newer version of Dok and related libraries.
Documentation can be freely reused and licensed under different licenses.

4.2  Long story

In this section we mean:
  • “use”: for calling a library in the combined-work, without relicensing its source-code inside the combined-work as part of it

  • “import the source code”: for including and maybe modify the source code of the library inside the combined-work, and relicense it as part of the combined-work, and under its license

  • “combined-work”: the code and shipped product “using” the LGPLv3+ library

LGPLv3+ can “import the source code” from LGPLv2+, LGPLv3+, APLv2 and other permissive licenses, relicensing it under LGPLv3+.
LGPLv3+ can “use” but not “import the source code” licensed under LGPLv2, and LGPLv3, and other propietary licenses
Propietary code can not “import the source code” licensed under LGPLv3+, without relicensing its code to LGPLv3+.
Propietary code can “use” LGPLv3+ source code, maintaining its propietary license in case it gives rights to the end-user to use different versions of the “used” LGPLv3+ libraries instead of the shipped one. If the combined-work is “using” dynamic LGPL libraries, the end-user can substitute the LGPL libraries with different versions, and the derived-work will use them automatically at run-time.
In case of DokMelody, many libraries are not distinct from the combined-work, but they are instantied and injected inside the combined-work at compile-time. So the vendor had to include (at moment of the shipping or under request of its end-users) its source-code (also obfuscated) or its object-code, with the building instructions for creating a new version of its combined-work, using newer/different versions of the “used” LGPL libraries and/or of the DokMelody compiler. The end-user must be informed of this possibility.
This affects only end-users with the right to use the original combined-work, i.e. users without a valid license can never rebuild and use the new version of the combined-work. Accordingly end-users inherit no rights to modify the vendor code vendor released under propietary license, but they have rights only for the LGPL parts.
It is not clear if LGPLv3+ code can be “used” on combined-work shipped on locked devices, where the user has no technical way to install new versions of it, and if the responsability is of the vendor of the derived-work or of the locked device.

4.3  Rationale

A more permissive license like APLv2 seems simpler to use, but:
  • there will be similar problems in case LGPL code is “used” or “imported”, and so the problem is only postponed, not completely avoided

  • the right to update a combined-work seem fair, when this involve free libraries: i.e. repairing a software should be legal and normal as repairing a mechanical device, also if the software is under a propietry license

  • security in IT is very important, and end-users with DokMelody can always rebuild a combined-work using more secure versions of the compiler and shipped libraries

  • JVM or .NET code is already a form of inspectable and specializable high-level object-code on which the end-user can update the called libraries and also the executing virtual machine, so the same right is enforced also for compiled DokMelody code


⦿ decision-record

1  Context

DokMelody can be used for different problem domains, and it can run in many different run-time environments.

2  Decision

Favour fork of DokMelody, and call them distributions.
The upstream DokMelody project will favour meta-programming and flexibility, but every distribution is a distinct project, with:
  • a specific usage-scenario/domain

  • a potentially distinct community of developers

  • a distinct name and marketing strategy

  • maybe an explicit reference to the upstream DokMelody distribution it is forking and specializing

3  Consequences

  • avoiding pointless discussions on things that must be managed in different ways

  • possibility to explore different technical solutions

  • possible confusion about too much different DokMelody distributions