API/ABI: restrict the symbol export to a determined public API (#227)

The goal of this PR is to properly determine what the public interface of libnetplan is. There is potentially a bit of ABI breakage, as symbols now default to hidden status unless explicitly marked otherwise, and said marking was done manually by looking at the current consumers I had on my system and trying to fill in the blanks.

The API, on the other hand, has been conscientiously broken, as most of what was exposed in the headers are now safely hidden away in our internal headers. This is by design, and AFAICT should not break existing code.

This PR depends on #230, as denoted by the merge commit in there. It should make independent review a bit easier :).

Given the fact that the main purpose of this PR is to limit the amount of symbols we export, we can safely assume that strictly speaking, there is ABI breakage. However, the whole point was to only expose the symbols that are in actual use out there in the real world.

As usual, the patchset has been edited expecting a review commit by commit, as the whole diff can be a bit daunting.


COMMITS:

* libnetplan: rework netplan,parse{-nm},util.h as public headers

This work involves splitting out some things from those headers into new
internal headers, and moving definitions around so that the public
headers are as self-contained as possible.

For the new internal headers, I decided to have a big "types.h" header
containing all the types used in a network definition. In itself, these
types aren't related to parsing except that the parser module is the
only producer, so I decided they could live on their own. This is also
the place where type-specific helpers can be found, such as
reset_netdef().

The various macros used to generate YAML were gathered up from both
source headers into a new yaml-helpers.h header, whereas the various
global state definitions were split off into their own headers, making
it easier to spot which areas of the code still rely on global state.
The remainder functions were moved into util-internal.h

This allows us to minimize the API exposed to the outside world.

V2:
  * Remove the extraneous struct net_definition line, as it is redundant
    with the typedef
  * Normalize all the symbol declarations to have the symbol name at the
    beginning of their own line, at least in the headers we touched.

V3:
  * Remove extraneous stdbool.h header
  * Split parse-helpers.h into yaml-helpers.h and util-internal.h
  * Add uuid as a dependency of the dbus generator to make it compile
    with the new lay of the land.
  * Add some missing copyright headers

* libnetplan: Properly mark the lib/bin interface

This patch cleanly marks which functions/objects are part of the public
library API, and which are meant to be consumed by our own binaries.

In order to reduce as much as possible the ABI dependencies between our
binaries and the library, I move the various generator modules into the
library as it make sense for them to access directly the objects. On the
other hand, both generate.c and dbus.c should be relatively trivial to
change to use getters and setters instead of direct structure access.

Those changes will be the object of later patches.

V3:
  * Makefile: consolidate the pkg-config calls and add back the LDFLAGS
    variable
  * Normalize the touched function declarations to always have the
    symbol name at the start of the line.

* libnetplan: add back ABI compatibility

Re-export (and recreate) various symbols that are needed by the
`generate` binary as shipped in the Ubuntu package 0.103-0ubuntu5

I have chosen a separate marker for those, in order to distinguish what
was exposed deliberately and by accident. That way, if we need to do a
SONAME bump, we can clean up the symbols marked with NETPLAN_ABI.

V3:
  * Normalize the declarations that are touched to always have the
    symbol name at the start of the line

* libnetplan: export Python-used symbols as internal

* libnetplan: hide all symbols by default

Only those marked by NETPLAN_{PUBLIC,INTERNAL,ABI} will be available to
the loader.

4 files changed, 154 insertions, 0 deletions

diff --git a/include/netplan.h b/include/netplan.h
new file mode 100644
index 0000000..9d30c26
--- /dev/null
+++ b/include/netplan.h
@@ -0,0 +1,29 @@
+/*
+ * Copyright (C) 2021 Canonical, Ltd.
+ * Author: Lukas Märdian <slyon@ubuntu.com>
+ *
+ * This program 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.
+ *
+ * This program 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 this program.  If not, see <http://www.gnu.org/licenses/>.
+ */
+
+#pragma once
+#define NETPLAN_PUBLIC __attribute__ ((visibility("default")))
+#define NETPLAN_INTERNAL __attribute__ ((visibility("default")))
+#define NETPLAN_ABI __attribute__ ((visibility("default")))
+
+/**
+ * Represent a configuration stanza
+ */
+typedef struct net_definition NetplanNetDefinition;
+
+NETPLAN_PUBLIC void
+write_netplan_conf(const NetplanNetDefinition* def, const char* rootdir);
diff --git a/include/parse-nm.h b/include/parse-nm.h
new file mode 100644
index 0000000..d83d665
--- /dev/null
+++ b/include/parse-nm.h
@@ -0,0 +1,26 @@
+/*
+ * Copyright (C) 2021 Canonical, Ltd.
+ * Author: Lukas Märdian <slyon@ubuntu.com>
+ *
+ * This program 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.
+ *
+ * This program 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 this program.  If not, see <http://www.gnu.org/licenses/>.
+ */
+
+#pragma once
+
+#include "netplan.h"
+#include <glib.h>
+
+#define NETPLAN_NM_EMPTY_GROUP "_"
+
+NETPLAN_PUBLIC gboolean
+netplan_parse_keyfile(const char* filename, GError** error);
diff --git a/include/parse.h b/include/parse.h
new file mode 100644
index 0000000..eda0260
--- /dev/null
+++ b/include/parse.h
@@ -0,0 +1,66 @@
+/*
+ * Copyright (C) 2016 Canonical, Ltd.
+ * Author: Martin Pitt <martin.pitt@ubuntu.com>
+ *
+ * This program 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.
+ *
+ * This program 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 this program.  If not, see <http://www.gnu.org/licenses/>.
+ */
+
+#pragma once
+#include "netplan.h"
+#include <glib.h>
+
+/****************************************************
+ * Parsed definitions
+ ****************************************************/
+
+typedef enum {
+    NETPLAN_DEF_TYPE_NONE,
+    /* physical devices */
+    NETPLAN_DEF_TYPE_ETHERNET,
+    NETPLAN_DEF_TYPE_WIFI,
+    NETPLAN_DEF_TYPE_MODEM,
+    /* virtual devices */
+    NETPLAN_DEF_TYPE_VIRTUAL,
+    NETPLAN_DEF_TYPE_BRIDGE = NETPLAN_DEF_TYPE_VIRTUAL,
+    NETPLAN_DEF_TYPE_BOND,
+    NETPLAN_DEF_TYPE_VLAN,
+    NETPLAN_DEF_TYPE_TUNNEL,
+    NETPLAN_DEF_TYPE_PORT,
+    /* Type fallback/passthrough */
+    NETPLAN_DEF_TYPE_NM,
+    NETPLAN_DEF_TYPE_MAX_
+} NetplanDefType;
+
+typedef enum {
+    NETPLAN_BACKEND_NONE,
+    NETPLAN_BACKEND_NETWORKD,
+    NETPLAN_BACKEND_NM,
+    NETPLAN_BACKEND_OVS,
+    NETPLAN_BACKEND_MAX_,
+} NetplanBackend;
+
+/****************************************************
+ * Functions
+ ****************************************************/
+
+NETPLAN_PUBLIC gboolean
+netplan_parse_yaml(const char* filename, GError** error);
+
+NETPLAN_PUBLIC GHashTable*
+netplan_finish_parse(GError** error);
+
+NETPLAN_PUBLIC guint
+netplan_clear_netdefs();
+
+NETPLAN_PUBLIC NetplanBackend
+netplan_get_global_backend();
diff --git a/include/util.h b/include/util.h
new file mode 100644
index 0000000..e7e1a0f
--- /dev/null
+++ b/include/util.h
@@ -0,0 +1,33 @@
+/*
+ * Copyright (C) 2016 Canonical, Ltd.
+ * Author: Martin Pitt <martin.pitt@ubuntu.com>
+ *
+ * This program 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.
+ *
+ * This program 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 this program.  If not, see <http://www.gnu.org/licenses/>.
+ */
+
+#pragma once
+
+#include <glib.h>
+#include "netplan.h"
+
+NETPLAN_PUBLIC gboolean
+netplan_delete_connection(const char* id, const char* rootdir);
+
+NETPLAN_PUBLIC gboolean
+netplan_generate(const char* rootdir);
+
+NETPLAN_PUBLIC gchar*
+netplan_get_id_from_nm_filename(const char* filename, const char* ssid);
+
+NETPLAN_PUBLIC gchar*
+netplan_get_filename_by_id(const char* netdef_id, const char* rootdir);