system/NetworkManager
system/NetworkManager
1
0
Fork 0
mirror of https://gitlab.freedesktop.org/NetworkManager/NetworkManager synced 2024-07-23 03:04:18 +00:00
Code Issues Actions Packages Projects Releases Wiki Activity

libnm: Override parts of nm-setting-docs.xml

Browse source 
Add "---dbus---" sections to the NMSetting property docs, in the same
style as the plugin docs, parse them out into a file
"nm-setting-docs-overrides.xml", and use them to override the GObject
property docs in nm-setting-docs.xml.

This lets us put more D-Bus-specific information in the setting docs,
without cluttering up the property docs, and it also lets us document
dbus-only properties.
This commit is contained in:
Dan Winship 2014-11-16 15:36:18 -05:00 committed by Dan Winship
parent 780d8bf2fe
commit 36156b70dc
12 changed files with 207 additions and 15 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

1
.gitignore vendored
View file

@ -166,6 +166,7 @@ valgrind-*.log
/libnm/nm-ifcfg-rh-docs.xml
/libnm/nm-keyfile-docs.xml
/libnm/nm-setting-docs.xml
/libnm/nm-setting-docs-overrides.xml
/libnm/tests/test-nm-client
/libnm/tests/test-remote-settings-client
/libnm/tests/test-secret-agent

8
libnm-core/nm-setting-bond.c
View file

@ -745,6 +745,14 @@ nm_setting_bond_class_init (NMSettingBondClass *setting_class)
_nm_utils_strdict_to_dbus,
_nm_utils_strdict_from_dbus);
/* ---dbus---
* property: interface-name
* format: string
* description: Deprecated in favor of connection.interface-name, but can
* be used for backward-compatibility with older daemons, to set the
* bond's interface name.
* ---end---
*/
_nm_setting_class_add_dbus_only_property (parent_class, "interface-name",
G_VARIANT_TYPE_STRING,
_nm_setting_get_deprecated_virtual_interface_name,

8
libnm-core/nm-setting-bridge.c
View file

@ -525,6 +525,14 @@ nm_setting_bridge_class_init (NMSettingBridgeClass *setting_class)
NM_SETTING_PARAM_INFERRABLE |
G_PARAM_STATIC_STRINGS));
/* ---dbus---
* property: interface-name
* format: string
* description: Deprecated in favor of connection.interface-name, but can
* be used for backward-compatibility with older daemons, to set the
* bridge's interface name.
* ---end---
*/
_nm_setting_class_add_dbus_only_property (parent_class, "interface-name",
G_VARIANT_TYPE_STRING,
_nm_setting_get_deprecated_virtual_interface_name,

62
libnm-core/nm-setting-ip4-config.c
View file

@ -578,12 +578,35 @@ nm_setting_ip4_config_class_init (NMSettingIP4ConfigClass *ip4_class)
G_PARAM_STATIC_STRINGS));
/* IP4-specific property overrides */
/* ---dbus---
* property: dns
* format: array of uint32
* description: Array of IP addresses of DNS servers (as network-byte-order
* integers)
* ---end---
*/
_nm_setting_class_transform_property (setting_class,
NM_SETTING_IP_CONFIG_DNS,
G_VARIANT_TYPE ("au"),
ip4_dns_to_dbus,
ip4_dns_from_dbus);
/* ---dbus---
* property: addresses
* format: array of array of uint32
* description: Deprecated in favor of the 'address-data' and 'gateway'
* properties, but this can be used for backward-compatibility with older
* daemons. Note that if you send this property the daemon will ignore
* 'address-data' and 'gateway'.
*
* Array of IPv4 address structures. Each IPv4 address structure is
* composed of 3 32-bit values; the first being the IPv4 address (network
* byte order), the second the prefix (1 - 32), and last the IPv4 gateway
* (network byte order). The gateway may be left as 0 if no gateway exists
* for that subnet.
* ---end---
*/
_nm_setting_class_override_property (setting_class,
NM_SETTING_IP_CONFIG_ADDRESSES,
G_VARIANT_TYPE ("aau"),
@ -597,12 +620,38 @@ nm_setting_ip4_config_class_init (NMSettingIP4ConfigClass *ip4_class)
ip4_address_labels_get,
NULL);
/* ---dbus---
* property: address-data
* format: array of vardict
* description: Array of IPv4 addresses. Each address dictionary contains at
* least 'address' and 'prefix' entries, containing the IP address as a
* string, and the prefix length as a uint32. Additional attributes may
* also exist on some addresses.
* ---end---
*/
_nm_setting_class_add_dbus_only_property (setting_class,
"address-data",
G_VARIANT_TYPE ("aa{sv}"),
ip4_address_data_get,
ip4_address_data_set);
/* ---dbus---
* property: routes
* format: array of array of uint32
* description: Deprecated in favor of the 'route-data' property, but this
* can be used for backward-compatibility with older daemons. Note that if
* you send this property the daemon will ignore 'route-data'.
*
* Array of IPv4 route structures. Each IPv4 route structure is composed
* of 4 32-bit values; the first being the destination IPv4 network or
* address (network byte order), the second the destination network or
* address prefix (1 - 32), the third being the next-hop (network byte
* order) if any, and the fourth being the route metric. If the metric is
* 0, NM will choose an appropriate default metric for the device. (There
* is no way to explicitly specify an actual metric of 0 with this
* property.)
* ---end---
*/
_nm_setting_class_override_property (setting_class,
NM_SETTING_IP_CONFIG_ROUTES,
G_VARIANT_TYPE ("aau"),
@ -610,6 +659,19 @@ nm_setting_ip4_config_class_init (NMSettingIP4ConfigClass *ip4_class)
ip4_routes_set,
NULL);
/* ---dbus---
* property: route-data
* format: array of vardict
* description: Array of IPv4 routes. Each route dictionary contains at
* least 'dest' and 'prefix' entries, containing the destination IP
* address as a string, and the prefix length as a uint32. Most routes
* will also have a 'gateway' entry, containing the gateway IP address as
* a string. If the route has a 'metric' entry (containing a uint32), that
* will be used as the metric for the route (otherwise NM will pick a
* default value appropriate to the device). Additional attributes may
* also exist on some routes.
* ---end---
*/
_nm_setting_class_add_dbus_only_property (setting_class,
"route-data",
G_VARIANT_TYPE ("aa{sv}"),

57
libnm-core/nm-setting-ip6-config.c
View file

@ -498,12 +498,33 @@ nm_setting_ip6_config_class_init (NMSettingIP6ConfigClass *ip6_class)
G_PARAM_STATIC_STRINGS));
/* IP6-specific property overrides */
/* ---dbus---
* property: dns
* format: array of byte array
* description: Array of IP addresses of DNS servers (in network byte order)
* ---end---
*/
_nm_setting_class_transform_property (setting_class,
NM_SETTING_IP_CONFIG_DNS,
G_VARIANT_TYPE ("aay"),
ip6_dns_to_dbus,
ip6_dns_from_dbus);
/* ---dbus---
* property: addresses
* format: array of legacy IPv6 address struct (a(ayuay))
* description: Deprecated in favor of the 'address-data' and 'gateway'
* properties, but this can be used for backward-compatibility with older
* daemons. Note that if you send this property the daemon will ignore
* 'address-data' and 'gateway'.
*
* Array of IPv6 address structures. Each IPv6 address structure is
* composed of an IPv6 address, a prefix length (1 - 128), and an IPv6
* gateway address. The gateway may be zeroed out if no gateway exists for
* that subnet.
* ---end---
*/
_nm_setting_class_override_property (setting_class,
NM_SETTING_IP_CONFIG_ADDRESSES,
G_VARIANT_TYPE ("a(ayuay)"),
@ -511,12 +532,35 @@ nm_setting_ip6_config_class_init (NMSettingIP6ConfigClass *ip6_class)
ip6_addresses_set,
NULL);
/* ---dbus---
* property: address-data
* format: array of vardict
* description: Array of IPv6 addresses. Each address dictionary contains at
* least 'address' and 'prefix' entries, containing the IP address as a
* string, and the prefix length as a uint32. Additional attributes may
* also exist on some addresses.
* ---end---
*/
_nm_setting_class_add_dbus_only_property (setting_class,
"address-data",
G_VARIANT_TYPE ("aa{sv}"),
ip6_address_data_get,
ip6_address_data_set);
/* ---dbus---
* property: routes
* format: array of legacy IPv6 route struct (a(ayuayu))
* description: Deprecated in favor of the 'route-data' property, but this
* can be used for backward-compatibility with older daemons. Note that if
* you send this property the daemon will ignore 'route-data'.
*
* Array of IPv6 route structures. Each IPv6 route structure is
* composed of an IPv6 address, a prefix length (1 - 128), an IPv6
* next hop address (which may be zeroed out if there is no next hop),
* and a metric. If the metric is 0, NM will choose an appropriate
* default metric for the device.
* ---end---
*/
_nm_setting_class_override_property (setting_class,
NM_SETTING_IP_CONFIG_ROUTES,
G_VARIANT_TYPE ("a(ayuayu)"),
@ -524,6 +568,19 @@ nm_setting_ip6_config_class_init (NMSettingIP6ConfigClass *ip6_class)
ip6_routes_set,
NULL);
/* ---dbus---
* property: route-data
* format: array of vardict
* description: Array of IPv6 routes. Each route dictionary contains at
* least 'dest' and 'prefix' entries, containing the destination IP
* address as a string, and the prefix length as a uint32. Most routes
* will also have a 'next-hop' entry, containing the next hop IP address as
* a string. If the route has a 'metric' entry (containing a uint32), that
* will be used as the metric for the route (otherwise NM will pick a
* default value appropriate to the device). Additional attributes may
* also exist on some routes.
* ---end---
*/
_nm_setting_class_add_dbus_only_property (setting_class,
"route-data",
G_VARIANT_TYPE ("aa{sv}"),

6
libnm-core/nm-setting-serial.c
View file

@ -301,6 +301,12 @@ nm_setting_serial_class_init (NMSettingSerialClass *setting_class)
* 111 ('o') for odd, or 110 ('n') for none.
* example: parity=n
* ---end---
* ---dbus---
* property: parity
* format: byte
* description: The connection parity: 69 (ASCII 'E') for even parity,
* 111 (ASCII 'o') for odd, 110 (ASCII 'n') for none.
* ---end---
*/
g_object_class_install_property
(object_class, PROP_PARITY,

8
libnm-core/nm-setting-team.c
View file

@ -171,6 +171,14 @@ nm_setting_team_class_init (NMSettingTeamClass *setting_class)
NM_SETTING_PARAM_INFERRABLE |
G_PARAM_STATIC_STRINGS));
/* ---dbus---
* property: interface-name
* format: string
* description: Deprecated in favor of connection.interface-name, but can
* be used for backward-compatibility with older daemons, to set the
* team's interface name.
* ---end---
*/
_nm_setting_class_add_dbus_only_property (parent_class, "interface-name",
G_VARIANT_TYPE_STRING,
_nm_setting_get_deprecated_virtual_interface_name,

7
libnm-core/nm-setting-vlan.c
View file

@ -806,6 +806,13 @@ nm_setting_vlan_class_init (NMSettingVlanClass *setting_class)
* but VLAN id from DEVICE takes precedence over VLAN_ID.
* example: PHYSDEV=eth0, VLAN_ID=12; or DEVICE=eth0.12
* ---end---
* ---dbus---
* property: interface-name
* format: string
* description: Deprecated in favor of connection.interface-name, but can
* be used for backward-compatibility with older daemons, to set the
* vlan's interface name.
* ---end---
*/
_nm_setting_class_add_dbus_only_property (parent_class, "interface-name",
G_VARIANT_TYPE_STRING,

7
libnm-core/nm-setting-wireless.c
View file

@ -1317,6 +1317,13 @@ nm_setting_wireless_class_init (NMSettingWirelessClass *setting_class)
* variable: (none)
* description: This property is deprecated and not handled by ifcfg-rh-plugin.
* ---end---
* ---dbus---
* property: security
* description: This property is deprecated, but can be set to the value
* '802-11-wireless-security' when a wireless security setting is also
* present in the connection dictionary, for compatibility with very old
* NetworkManager daemons.
* ---end---
*/
_nm_setting_class_add_dbus_only_property (parent_class, "security",
G_VARIANT_TYPE_STRING,

12
libnm/Makefile.am
View file

@ -184,15 +184,23 @@ check-local:
if BUILD_SETTING_DOCS
noinst_DATA = nm-setting-docs.xml nm-keyfile-docs.xml nm-ifcfg-rh-docs.xml
noinst_DATA = \
nm-setting-docs-overrides.xml \
nm-setting-docs.xml \
nm-keyfile-docs.xml \
nm-ifcfg-rh-docs.xml
docs_sources = $(filter-out nm-core-enum-types.c,$(libnm_core_sources))
nm-setting-docs.xml: generate-setting-docs.py $(docs_sources) | NM-1.0.gir NM-1.0.typelib libnm.la
nm-setting-docs-overrides.xml: generate-plugin-docs.pl $(docs_sources)
$(srcdir)/generate-plugin-docs.pl dbus $(top_srcdir)/libnm-core $@
nm-setting-docs.xml: generate-setting-docs.py $(docs_sources) nm-setting-docs-overrides.xml | NM-1.0.gir NM-1.0.typelib libnm.la
export GI_TYPELIB_PATH=$(abs_builddir)$${GI_TYPELIB_PATH:+:$$GI_TYPELIB_PATH}; \
export LD_LIBRARY_PATH=$(abs_builddir)/.libs$${LD_LIBRARY_PATH:+:$$LD_LIBRARY_PATH}; \
$(srcdir)/generate-setting-docs.py \
--gir $(builddir)/NM-1.0.gir \
--overrides $(builddir)/nm-setting-docs-overrides.xml \
--output $@
nm-keyfile-docs.xml: generate-plugin-docs.pl $(docs_sources)

2
libnm/generate-plugin-docs.pl
View file

@ -55,7 +55,6 @@ my @data;
my $fo;
(scalar @ARGV == 3) or die "Usage: $0 <plugin> <srcdir> <output-xml-file>\n";
($ARGV[0] eq "keyfile" || $ARGV[0] eq "ifcfg-rh") or die "Allowed <plugin> values: keyfile, ifcfg-rh\n";
my ($plugin, $srcdir, $output) = @ARGV;
my $start_tag = "---$plugin---\\s*\$";
my $end_tag = '---end---';
@ -155,6 +154,7 @@ sub process_data {
my $exam = $yaml_data->{example} // "";
my $desc = $yaml_data->{description} // "";
chomp($name, $var, $format, $values, $def, $exam, $desc);
escape_xml_chars($name, $var, $format, $values, $def, $exam, $desc);
my $foo = sprintf("<property name=\"%s\" variable=\"%s\" format=\"%s\" values=\"%s\" ".
"default=\"%s\" example=\"%s\" description=\"%s\"/>",

44
libnm/generate-setting-docs.py
View file

@ -152,6 +152,7 @@ def usage():
parser = argparse.ArgumentParser()
parser.add_argument('-g', '--gir', metavar='FILE', help='NM-1.0.gir file')
parser.add_argument('-x', '--overrides', metavar='FILE', help='documentation overrides file')
parser.add_argument('-o', '--output', metavar='FILE', help='output file')
args = parser.parse_args()
@ -172,6 +173,8 @@ settings = sorted(settings, key=lambda setting: setting.attrib['{%s}symbol-prefi
init_constants(girxml, settings)
overrides = ET.parse(args.overrides).getroot()
outfile.write("""<?xml version=\"1.0\"?>
<!DOCTYPE nm-setting-docs [
<!ENTITY quot "&#34;">
@ -188,24 +191,41 @@ for settingxml in settings:
outfile.write(" <setting name=\"%s\">\n" % setting.props.name)
properties = sorted(GObject.list_properties(setting), key=lambda prop: prop.name)
for pspec in properties:
propxml = settingxml.find('./gi:property[@name="%s"]' % pspec.name, ns_map)
if propxml is None:
propxml = basexml.find('./gi:property[@name="%s"]' % pspec.name, ns_map)
if propxml is None:
propxml = ipxml.find('./gi:property[@name="%s"]' % pspec.name, ns_map)
setting_properties = { prop.name: prop for prop in GObject.list_properties(setting) }
setting_overrides = { override.attrib['name']: override for override in overrides.findall('./setting[@name="%s"]/property' % setting.props.name) }
value_type = get_prop_type(setting, pspec, propxml)
value_desc = get_docs(setting, pspec, propxml)
default_value = get_default_value(setting, pspec, propxml)
properties = sorted(set.union(set(setting_properties.keys()), set(setting_overrides.keys())))
for prop in properties:
value_type = None
value_desc = None
default_value = None
if prop in setting_properties:
pspec = setting_properties[prop]
propxml = settingxml.find('./gi:property[@name="%s"]' % pspec.name, ns_map)
if propxml is None:
propxml = basexml.find('./gi:property[@name="%s"]' % pspec.name, ns_map)
if propxml is None:
propxml = ipxml.find('./gi:property[@name="%s"]' % pspec.name, ns_map)
value_type = get_prop_type(setting, pspec, propxml)
value_desc = get_docs(setting, pspec, propxml)
default_value = get_default_value(setting, pspec, propxml)
if prop in setting_overrides:
override = setting_overrides[prop]
if override.attrib['format'] != '':
value_type = override.attrib['format']
if override.attrib['description'] != '':
value_desc = override.attrib['description']
if default_value is not None:
outfile.write(" <property name=\"%s\" type=\"%s\" default=\"%s\" description=\"%s\" />\n" %
(pspec.name, value_type, escape(default_value), escape(value_desc)))
(prop, value_type, escape(default_value), escape(value_desc)))
else:
outfile.write(" <property name=\"%s\" type=\"%s\" description=\"%s\" />\n" %
(pspec.name, value_type, escape(value_desc)))
(prop, value_type, escape(value_desc)))
outfile.write(" </setting>\n")