.. This file is part of Sympathy for Data.
.. Copyright (c) 2022 Combine Control Systems AB
..
.. Sympathy for Data is free software: you can redistribute it and/or modify
.. it under the terms of the GNU General Public License as published by
.. the Free Software Foundation, version 3 of the License.
..
.. Sympathy for Data is distributed in the hope that it will be useful,
.. but WITHOUT ANY WARRANTY; without even the implied warranty of
.. MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
.. GNU General Public License for more details.
..
.. You should have received a copy of the GNU General Public License
.. along with Sympathy for Data.  If not, see <http://www.gnu.org/licenses/>.

.. _`use_libraries`:

Libraries
=========

A Library is a container for nodes and plugins that makes them available for
use in Sympathy. On the computer, a library is a folder with a certain file
structure, for details see *Library structure* in :ref:`libraries`.

Additional libraries are generally referred to as third-party libraries. When
you have downloaded (or otherwise obtained) a third-party library you can add
it to Sympathy.

Libraries can be added globally, for all Sympathy instances, or locally, for
specific workflows. The current workflow and the global settings determine
which workflows that are currently active. Nodes from all active libraries are
shown in the :ref:`node_library_window`.

For information about how to create new libraries, see :ref:`library_wizard`.

Libraries have some basic properties, such as, a name, a version. And can
optionally provide its own example flows and HTML documentation.


Adding Libraries
--------------------

Libraries can be added to the global list of libraries in :ref:`Preferences
<preferences_node_libraries>` or to the list of libraries for any open workflow
(root or linked) in Properties (right-click, *Properties* -> *Libraries*).

.. note::

    Advanced: it is possible to add libraries globally, as
    python packages, by using `pip install ...`. This is how the standard
    library is installed.

Local workflow libraries rely on paths (typically relative) and can simplify
sharing, when the paths are reliable across systems. Local libraries is often a
good choice since they make dependencies explicit and shareable.

Global libraries is a good choice to add a few libraries that you always want
to use.


Adding nodes
-------------

New nodes can be built using subflows of existing nodes. These :ref:`Subflow
Nodes <flows_in_library>` can then be added to an active library.

.. note::

    Advanced: new nodes based on Python code can be added to an
    active library by following the instructions in :ref:`node_wizard`.


Missing nodes
-------------

When opening a workflow that uses nodes that are not found among the currently
active libraries these will be replaced, in the workflow, by non-usable
placeholder elements: :ref:`node_missing_nodes` and
:ref:`missing_subflows`. The solution to restore the necessary nodes is to add
the libraries that contain them. This can be done by adding the libraries
globally or by adding them to the root of the workflow where they are missing.

It is also possible to use another workflow that adds the necessary libraries
and somehow links to the original workflow. This works because local workflow
libraries are considered per root workflow and includes the libraries for any
linked subflows.