LibreCores Documentation

If you are a developer of a LibreCore you are probably a good developer of HDL designs. You are planning this very cool small functional block that makes life so much easier for other programmers? Or you have build an entire processor core for the last years? That is very cool and this is a good starting point to get people involved in your core. On this page we assembled some quick start for you into how to publish your code, what license to choose and how to build a community around your block.

Publish your code

You most probably know that sending around zip files with your code to whoever you think might be interested or putting it on a website is not the favored way of publishing anymore.

Instead, source code is managed in code revision systems, like subversion or git. Such repositories are widely used in software projects and also open source digital designs benefit a lot from such systems. While subversion is still be used a lot in closed projects, we highly encourage using git for your source code management. It easily allows to have different local branches where you can play around with features and optimizations, it makes merging work of you or other contributors very easy, and it has great support by online platforms, just to name a few benefits.

Where to host your code?

While LibreCores.org will be the community hub to publish your work or find cores, we will not be a hosting site. There are free services that can do this way better! Most known is Github, but also BitBucket has quite a use base. It is good to search around the platforms to learn about the benefits of the platforms. Just to give you an idea about what you do there:

You may now think: "So why should I ever come back to LibreCores.org?" Fair question as we are still in the process of building the core of our platform. But just to give you an idea what LibreCores.org is about then, those are the features we are planning:

When to publish my code?

A common question is when to publish a code. This is a question not original to digital design, but of course care must be taken if you think people may actually pick it up and build a chip from it. Of course they should carefully test it, but you should highlight the state of your core honestly.

In our opinion it is good to start with publishing your code early. It gives the community the chance to learn about your code and contribute at early stages. That helps you and helps the community in being able to follow your development.

Of course there are situation where you may want to put out the code after it is fully tested and documented. That is why source code hosting websites like Github have releases for. You should develop your IP core and whenever you reached a milestone, make this a release of your core that is supposed to be stable and tested, while you can go on in your repository with cool new features.

We highly encourage to make your code public as soon as you are sure you want to follow this project and work on a LibreCore. This helps you involving the community from early on.

Licensing

Another important aspect is to add a license to your code. The license defines how people can use your code and what obligations they have.

The first question is how your code can be used. That answer is actually simple: By downloading it. There are no further restrictions, thats the idea of open source. So, despite we can understand the idea behind adding a non-commercial clause or a non-military clause, we highly discourage you to add any such clauses to your licenses. They are against the definition of open source (see Open Source Initiative, crit. 6: "No Discrimination Against Fields of Endeavor - The license must not restrict anyone from making use of the program in a specific field of endeavor. For example, it may not restrict the program from being used in a business, or from being used for genetic research.").

There are more options when it comes to obligations and open source licenses vary in the permissiveness they give the user to deploy and release the work derived from your code. The permissiveness of the license is a matter for the licensor (the author, copyright owner) and often depends on their position regarding reuse of the design. The more permissive the license, the less requirements on future users and developers of the IP. Less permissive licenses have more restrictions, which generally ensure the derivative works remain as free and open as the original work. These less permissive licenses, also known as copyleft licenses for how they enforce the work’s openness, vary greatly from weak to strong copyleft and primarily indicate how a derivative work may be licensed - whether it must be entirely released under an equivalently open license (strong copyleft, reciprocal licenses) or not.

Almost all strong copyleft licenses have been written to apply to software, and the mechanisms they specify (binary linking, for example) that qualify a derivative work to be released under the same terms and conditions - guaranteeing the IP remain open and free to be reused - are problematic attempting to apply them a HDL design.

Once you come to a decision what kind of license you want to use, there are a few licenses that are FOSSi-compatbile in our opinion and that you should consider using: