mirror of
https://github.com/xodio/xod.git
synced 2026-03-14 20:56:52 +01:00
127 lines
4.2 KiB
Markdown
127 lines
4.2 KiB
Markdown
---
|
||
title: Creating Libraries
|
||
---
|
||
|
||
# Creating Libraries
|
||
|
||
This article will guide you through the process of creating and publishing your
|
||
own library.
|
||
|
||
## Starting a library
|
||
|
||
Here's a little secret: libraries and [projects](../projects/) in XOD have no
|
||
technical difference. The distinction is conventional. Your project becomes a
|
||
library when you decide that it is.
|
||
|
||
To start a new library, hit “File → New Project.”
|
||
|
||
## Crafting nodes
|
||
|
||
[Make the nodes](/docs/guides/#making-own-nodes) you want to be in the library
|
||
like you would do for any project.
|
||
|
||
[Documenting the nodes](../documenting-nodes/) you're going to share is
|
||
extremely important for libraries. A lack of short descriptions for nodes and
|
||
their pins will very likely ruin your effort and make the library unusable to
|
||
others.
|
||
|
||
## Adding example patches
|
||
|
||
The obvious step is to test your nodes in action before sharing them. One of the
|
||
possible ways to do so is by creating several _example patches_. They are
|
||
regular patches with a conventional `-example` suffix in their name like
|
||
`mcp3002-adc-example`.
|
||
|
||
On such patch, place the node to be tested and use the most basic input/output
|
||
facilities: watches, constants, LEDs, pots, and buttons. Having done that, you
|
||
focus on the node under the test. Upload the patch to verify that the node works
|
||
as expected. Later, any xoder can view and upload the same example as well to
|
||
learn how the node works.
|
||
|
||
## Setting metadata
|
||
|
||
To publish a library, you are required to set several project-level fields. All
|
||
of them are accessible through the “Edit → Project Preferences” dialog.
|
||
|
||
|
||
|
||
<table class="ui definition table">
|
||
<tbody>
|
||
<tr>
|
||
<td>Name</td>
|
||
<td>
|
||
The library will be available to others under the
|
||
<code>yourusername/name</code> full name. Use a short and descriptive
|
||
name under 20 characters.
|
||
</td>
|
||
</tr>
|
||
<tr>
|
||
<td>License</td>
|
||
<td>
|
||
OSS license name defining terms of use for your work. Choose between
|
||
MIT, BSD, GPL, etc.
|
||
</td>
|
||
</tr>
|
||
<tr>
|
||
<td>Version</td>
|
||
<td>
|
||
The <a href="https://semver.org/" target="_blank">semver</a> tag for
|
||
the upcoming publication. If you're about to publish a library for the
|
||
first time, as a rule of thumb, start with <code>1.0.0</code>.
|
||
</td>
|
||
</tr>
|
||
<tr>
|
||
<td>Description</td>
|
||
<td>
|
||
One- or two-tweet-long description for your library. It is shown on <a
|
||
href="https://xod.io/libs/">https://xod.io/libs/</a> and inside XOD
|
||
IDE.
|
||
</td>
|
||
</tr>
|
||
</tbody>
|
||
</table>
|
||
|
||
## Publish
|
||
|
||
When ready, hit “File → Publish Library.” Review the proposed effects and click
|
||
“Publish.”
|
||
|
||
|
||
|
||
A few seconds later, your new library will be available at the
|
||
[Libraries](/libs/) section on the XOD site. Feel free to announce your
|
||
treasure to [XOD community](https://forum.xod.io).
|
||
|
||
## Using own library
|
||
|
||
To use a library you've published already in any other project, think of it as
|
||
of a third-party library. That is, hit “File → Add Library” and
|
||
[install](../using-libraries/#installing-a-library) own library, just like
|
||
anyone else would do.
|
||
|
||
## Updating
|
||
|
||
If you have published a larger-than-trivial library, you will likely want to
|
||
release an update for it sooner or later. To do so:
|
||
|
||
1. Open the library project.
|
||
2. Make the required changes.
|
||
3. Update the metadata.
|
||
4. Publish again.
|
||
|
||
A special note on updating the version field: You are not allowed to re-publish
|
||
the same version as any you have posted before. The version number must be
|
||
_bumped_. The best practice is to follow the [semver](https://semver.org/)
|
||
convention:
|
||
|
||
* increment the last number (1.3.1 → 1.3.2) if you're just fixing bugs or
|
||
improving the documentation;
|
||
* increment the middle number (1.3.1 → 1.4.0) if you're releasing new features
|
||
preserving backward compatibility – i.e., you are adding new features, not
|
||
changing existing ones; and
|
||
* increment the first number (1.3.1 → 2.0.0) if you have made breaking changes.
|
||
|
||
Once the new version is published, to make it visible to your other projects,
|
||
update the local installation of your own library by hitting “File → Add
|
||
Library” again.
|