Skip to content

Commit fa1aa9f

Browse files
sgallaghersgallagher
committed
Add modulemd.h header and docs
Signed-off-by: Stephen Gallagher <[email protected]>
1 parent 2391b14 commit fa1aa9f

File tree

5 files changed

+220
-0
lines changed

5 files changed

+220
-0
lines changed

‎modulemd/meson.build‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -117,6 +117,7 @@ test_v1_srcs = files(
117117

118118

119119
modulemd_v2_srcs = files(
120+
'v2/modulemd.c',
120121
'v2/modulemd-buildopts.c',
121122
'v2/modulemd-component.c',
122123
'v2/modulemd-component-module.c',
@@ -140,6 +141,7 @@ modulemd_v2_srcs = files(
140141
)
141142

142143
modulemd_v2_hdrs = files(
144+
'v2/include/modulemd-2.0/modulemd.h',
143145
'v2/include/modulemd-2.0/modulemd-buildopts.h',
144146
'v2/include/modulemd-2.0/modulemd-component.h',
145147
'v2/include/modulemd-2.0/modulemd-component-module.h',

‎modulemd/v2/include/modulemd-2.0/modulemd.h‎

Lines changed: 189 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,189 @@
1+
/*
2+
* This file is part of libmodulemd
3+
* Copyright (C) 2018 Red Hat, Inc.
4+
*
5+
* Fedora-License-Identifier: MIT
6+
* SPDX-2.0-License-Identifier: MIT
7+
* SPDX-3.0-License-Identifier: MIT
8+
*
9+
* This program is free software.
10+
* For more information on the license, see COPYING.
11+
* For more information on free software, see <https://www.gnu.org/philosophy/free-sw.en.html>.
12+
*/
13+
14+
#pragma once
15+
16+
#include "modulemd-buildopts.h"
17+
#include "modulemd-component.h"
18+
#include "modulemd-component-module.h"
19+
#include "modulemd-component-rpm.h"
20+
#include "modulemd-defaults.h"
21+
#include "modulemd-defaults-v1.h"
22+
#include "modulemd-dependencies.h"
23+
#include "modulemd-deprecated.h"
24+
#include "modulemd-module.h"
25+
#include "modulemd-module-index.h"
26+
#include "modulemd-module-index-merger.h"
27+
#include "modulemd-module-stream.h"
28+
#include "modulemd-module-stream-v1.h"
29+
#include "modulemd-module-stream-v2.h"
30+
#include "modulemd-profile.h"
31+
#include "modulemd-service-level.h"
32+
#include "modulemd-subdocument-info.h"
33+
#include "modulemd-translation.h"
34+
#include "modulemd-translation-entry.h"
35+
36+
G_BEGIN_DECLS
37+
38+
39+
/**
40+
* SECTION: modulemd
41+
* @title: Modulemd
42+
* @stability: stable
43+
* @short_description: User's Guide for libmodulemd
44+
*
45+
* # Working with repodata (DNF use-case) #
46+
* The libmodulemd API provides a number of convenience tools for interacting
47+
* with repodata (that is, streams of YAML that contains information on
48+
* multiple streams, default data and translations). The documentation will use
49+
* two repositories, called "fedora" and "updates" for demonstrative purposes.
50+
* It will assume that the content of the YAML module metadata from those two
51+
* repositories have been loaded into string variables "fedora_yaml" and
52+
* "updates_yaml", respectively.
53+
*
54+
* First step is to load the metadata from these two repositories into
55+
* #ModulemdModuleIndex objects. This is done as follows:
56+
*
57+
* In C:
58+
* |[<!-- language="C" -->
59+
* fedora_index = modulemd_module_index_new();
60+
* ret = modulemd_module_index_update_from_string(fedora_index,
61+
* fedora_yaml,
62+
* &failures,
63+
* &error);
64+
*
65+
* updates_index = modulemd_module_index_new();
66+
* ret = modulemd_module_index_update_from_string(updates_index,
67+
* updates_yaml,
68+
* &failures,
69+
* &error);
70+
* ]|
71+
*
72+
* The @failures argument will return any subdocuments in the YAML stream
73+
* that could not be parsed or validated successfully. In the event that the
74+
* stream as a whole could not be parsed, @error will be set accordingly.
75+
*
76+
* In python:
77+
*
78+
* |[<!-- language="Python" -->
79+
* fedora_index = Modulemd.ModuleIndex.new()
80+
* ret, failures = fedora_index.update_from_string(fedora_yaml)
81+
*
82+
* fedora_index = Modulemd.ModuleIndex.new()
83+
* ret, failures = updates_index.update_from_string(updates_yaml)
84+
* ]|
85+
*
86+
* Since it doesn't really make sense to view the contents from separate
87+
* repositories in isolation (in most cases), the next step is to merge the
88+
* two indexes into a combined one:
89+
*
90+
* In C:
91+
* |[<!-- language="C" -->
92+
* merger = modulemd_module_index_merger_new()
93+
* modulemd_module_index_merger_associate_index (merger, fedora_index, 0);
94+
* modulemd_module_index_merger_associate_index (merger, updates_index, 0);
95+
*
96+
* merged_index = modulemd_module_index_merger_resolve (merger, &error);
97+
* ]|
98+
*
99+
* In Python:
100+
* |[<!-- language="Python" -->
101+
* merger = Modulemd.ModuleIndexMerger.new()
102+
*
103+
* merger.associate_index(fedora_index, 0)
104+
* merger.associate_index(updates_index, 0)
105+
*
106+
* merged_index = merger.resolve()
107+
* ]|
108+
*
109+
* At this point, you now have either a complete view of the merged repodata,
110+
* or else have received an error describing why the merge was unable to
111+
* complete successfully. Additionally, it should be noted that the combined
112+
* metadata in any #ModulemdModuleIndex will have all of its component parts
113+
* upgraded to match the highest version of those objects seen. So for example
114+
* if the repodata has a mix of v1 and v2 #ModuleStream objects, the index will
115+
* contain only v2 objects (with the v1 objects automatically upgraded
116+
* internally).
117+
*
118+
* At this point, we can start operating on the retrieved data. This guide will
119+
* give only a brief overview of the most common operations. See the API
120+
* specification for a full list of information that can be retrieved.
121+
*
122+
* ## Discover the default stream for a particular module.
123+
* |[<!-- language="Python" -->
124+
* module = merged_index.get_module ('modulename')
125+
* defaults = module.get_defaults()
126+
* print ('Default stream for modulename is %s' % (
127+
* defaults.get_default_stream())
128+
* ]|
129+
*
130+
* ## Get the list of RPMs defining the public API for a particular module NSVC
131+
* |[<!-- language="Python" -->
132+
* module = merged_index.get_module ('modulename')
133+
* stream = module.get_stream_by_NSVC('modulestream', 1, 'deadbeef')
134+
* api_list = stream.get_rpm_api()
135+
* ]|
136+
*
137+
* ## Retrieve the modular runtime dependencies for a particular module NSVC
138+
* |[<!-- language="Python" -->
139+
* module = merged_index.get_module ('modulename')
140+
* stream = module.get_stream_by_NSVC('modulestream', 1, 'deadbeef')
141+
* deps_list = stream.get_dependencies()
142+
*
143+
* for dep in deps_list:
144+
* depstream_list = dep.get_runtime_streams('depstreamname')
145+
* <do_stuff>
146+
* ]|
147+
*
148+
*
149+
* # Working with a single module stream (Packager/MBS use-case)
150+
* One limitation of the #ModulemdModuleIndex format is that it requires that
151+
* all module streams loaded into it have both a name and a stream name. This
152+
* however is not possible when dealing with streams such as a packager would
153+
* be using (since the build-system auto-generates the module name and stream
154+
* name from the git repository information. In this case, we need to work
155+
* with a single module stream document at a time. For this, we will use the
156+
* #ModulemdModuleStream interface.
157+
*
158+
* This example will assume that the module name and stream name have already
159+
* been determined from the repodata and that they are stored in string
160+
* variables named 'module_name' and 'stream_name', respectively.
161+
*
162+
* |[<!-- language="Python" -->
163+
* stream = Modulemd.ModuleStream.read_file ('/path/to/module_name.yaml',
164+
* module_name,
165+
* stream_name)
166+
* v2_stream = stream.upgrade(Modulemd.ModuleStreamVersion.TWO)
167+
* v2_stream.validate()
168+
* ]|
169+
*
170+
* In the example above, we upgraded the stream to v2, in case we were reading
171+
* from v1 metadata. This will allow us to avoid having to manage multiple
172+
* code-paths and support only the latest we understand. After that, it calls
173+
* validate() to ensure that the content that was read in was valid both
174+
* syntactically and referentially.
175+
*/
176+
177+
178+
/**
179+
* modulemd_get_version:
180+
*
181+
* Returns: (transfer none): A string describing the version of libmodulemd.
182+
*
183+
* Since: 2.0
184+
*/
185+
const gchar *
186+
modulemd_get_version (void);
187+
188+
189+
G_END_DECLS

‎modulemd/v2/meson.build‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -23,6 +23,13 @@ endif
2323

2424
enums = gnome.mkenums_simple ('modulemd-enums', sources : modulemd_v2_hdrs)
2525

26+
cdata = configuration_data()
27+
cdata.set_quoted('LIBMODULEMD_VERSION', libmodulemd_v2_version)
28+
configure_file(
29+
output : 'config.h',
30+
configuration : cdata
31+
)
32+
2633
modulemd_v2_lib = library(
2734
'modulemd',
2835
sources : modulemd_v2_srcs + enums,

‎modulemd/v2/modulemd-v2-docs.xml‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -35,6 +35,7 @@
3535
</partintro>
3636
<chapter>
3737
<title>Modulemd 2.0 Public API</title>
38+
<xi:include href="xml/modulemd.xml"/>
3839
<xi:include href="xml/modulemd-buildopts.xml"/>
3940
<xi:include href="xml/modulemd-component.xml"/>
4041
<xi:include href="xml/modulemd-component-module.xml"/>

‎modulemd/v2/modulemd.c‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
/*
2+
* This file is part of libmodulemd
3+
* Copyright (C) 2018 Red Hat, Inc.
4+
*
5+
* Fedora-License-Identifier: MIT
6+
* SPDX-2.0-License-Identifier: MIT
7+
* SPDX-3.0-License-Identifier: MIT
8+
*
9+
* This program is free software.
10+
* For more information on the license, see COPYING.
11+
* For more information on free software, see <https://www.gnu.org/philosophy/free-sw.en.html>.
12+
*/
13+
14+
#include "modulemd.h"
15+
#include "config.h"
16+
17+
const gchar *
18+
modulemd_get_version (void)
19+
{
20+
return LIBMODULEMD_VERSION;
21+
}

0 commit comments

Comments
 (0)