Skip to content

Commit

Permalink
Merge pull request #343 from mmathesius/doc-sync-readme
Browse files Browse the repository at this point in the history 
Synchronize the user docs in the main header file and the repo's README
  • Loading branch information
@sgallagher
sgallagher authored Jul 19, 2019
2 parents 649d094 + fd2550a commit 0a42e0c
Show file tree
Hide file tree
Showing 2 changed files with 147 additions and 69 deletions.
70 changes: 42 additions & 28 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -29,8 +29,8 @@ with repodata (that is, streams of YAML that contains information on multiple
streams, default data and translations). The documentation will use two
repositories, called "fedora" and "updates" for demonstrative purposes. It
will assume that the content of the YAML module metadata from those two
repositories have been loaded into string variables `"fedora_yaml"` and
`"updates_yaml"`, respectively.
repositories have been loaded into string variables `fedora_yaml` and
`updates_yaml`, respectively.

First step is to load the metadata from these two repositories into
ModulemdModuleIndex objects. This is done as follows:
Expand Down Expand Up @@ -91,8 +91,8 @@ At this point, you now have either a complete view of the merged repodata,
or else have received an error describing why the merge was unable to
complete successfully. Additionally, it should be noted that the combined
metadata in any ModulemdModuleIndex will have all of its component parts
upgraded to match the highest version of those objects seen. So for
example if the repodata has a mix of v1 and v2 ModuleStream objects, the
upgraded to match the highest version of those objects seen. So for example
if the repodata has a mix of v1 and v2 ModulemdModuleStream objects, the
index will contain only v2 objects (with the v1 objects automatically
upgraded internally).

Expand All @@ -103,22 +103,22 @@ specification for a full list of information that can be retrieved.
## Discover the default stream for a particular module.
## C
```C
ModulemdModule * module = modulemd_module_index_get_module (merged_index, "modulename");
ModulemdDefaults * defaults = modulemd_module_get_defaults (module);
printf ("Default stream for modulename is %s\n",
modulemd_defaults_v1_get_default_stream (MODULEMD_DEFAULTS_V1 (defaults), NULL));
```
ModulemdModule * module = modulemd_module_index_get_module (merged_index, "modulename");
ModulemdDefaults * defaults = modulemd_module_get_defaults (module);
printf ("Default stream for modulename is %s\n",
modulemd_defaults_v1_get_default_stream (MODULEMD_DEFAULTS_V1 (defaults), NULL));
```
## Python
```python
module = merged_index.get_module ('modulename')
defaults = module.get_defaults()
print ('Default stream for modulename is %s' % (
module = merged_index.get_module ('modulename')
defaults = module.get_defaults()
print ('Default stream for modulename is %s' % (
defaults.get_default_stream())
```
```

## Get the list of RPMs defining the public API for a particular module NSVCA
First, query the Modulemd.ModuleIndex for the module with a given name.
First, query the ModulemdModuleIndex for the module with a given name.
## C
```C
ModulemdModule * module = modulemd_module_index_get_module (merged_index, "modulename");
Expand All @@ -129,27 +129,33 @@ ModulemdModule * module = modulemd_module_index_get_module (merged_index, "modul
module = merged_index.get_module ('modulename')
```

Then, query the Modulemd.Module for the Modulemd.ModuleStream associated with the provided NSVCA
(name-stream-version-context-architechture identifier).
Then, query the ModulemdModule for the ModulemdModuleStream associated with the
provided NSVCA (name-stream-version-context-architecture identifier).
## C
```C
ModulemdModuleStream * stream = modulemd_module_get_stream_by_NSVCA (module, "modulestream", 0, "deadbeef", "coolarch", &error);
ModulemdModuleStream * stream = modulemd_module_get_stream_by_NSVCA (module,
"modulestream",
0,
"deadbeef",
"coolarch",
&error);
```

## Python
```python
stream = module.get_stream_by_NSVCA('modulestream', 0, 'deadbeef', 'coolarch')
stream = module.get_stream_by_NSVCA('modulestream', 0, 'deadbeef', 'coolarch')
```

Lastly, read the RPM API from the Modulemd.ModuleStream. Here, `api_list` is a list of strings containing package names.
Lastly, read the RPM API from the ModulemdModuleStream. Here, `api_list` is
a list of strings containing package names.
## C
```C
GStrv api_list = modulemd_module_stream_v2_get_rpm_api_as_strv (MODULEMD_MODULE_STREAM_V2 (stream));
```

## Python
```python
api_list = stream.get_rpm_api()
api_list = stream.get_rpm_api()
```

## Retrieve the modular runtime dependencies for a particular module NSVCA
Expand All @@ -167,12 +173,12 @@ for (gint i = 0; i < deps_list->len; i++)
## Python
```python
module = merged_index.get_module ('modulename')
stream = module.get_stream_by_NSVCA('modulestream', 0, 'deadbeef', 'coolarch')
deps_list = stream.get_dependencies()
for dep in deps_list:
depstream_list = dep.get_runtime_streams('depstreamname')
<do_stuff>
module = merged_index.get_module ('modulename')
stream = module.get_stream_by_NSVCA('modulestream', 0, 'deadbeef', 'coolarch')
deps_list = stream.get_dependencies()
for dep in deps_list:
depstream_list = dep.get_runtime_streams('depstreamname')
<do_stuff>
```

# Working with a single module stream (Packager/MBS use-case)
Expand All @@ -187,7 +193,7 @@ use the ModulemdModuleStream interface.

This example will assume that the module name and stream name have
already been determined from the repodata and that they are stored in
string variables named 'module_name' and 'stream_name', respectively.
string variables named `module_name` and `stream_name`, respectively.

## Python
```python
Expand All @@ -198,7 +204,15 @@ stream = Modulemd.ModuleStream.read_file ('/path/to/module_name.yaml',
v2_stream = stream.upgrade(Modulemd.ModuleStreamVersionEnum.TWO)
v2_stream.validate()
```
In the example above, we upgraded the stream to v2, in case we were reading from v1 metadata. This will allow us to avoid having to manage multiple code-paths and support only the latest we understand. After that, it calls validate() to ensure that the content that was read in was valid both syntactically and referentially.
In the example above, we upgraded the stream to v2, in case we were reading
from v1 metadata. This will allow us to avoid having to manage multiple
code-paths and support only the latest we understand. After that, it calls
validate() to ensure that the content that was read in was valid both
syntactically and referentially.

Also available is `Modulemd.ModuleStreamVersionEnum.LATEST` which will
always represent the highest-supported version of the
ModulemdModuleStream metadata format. This may change at any time.

# Getting started with developing
## Prerequisites
Expand Down
146 changes: 105 additions & 41 deletions modulemd/include/modulemd-2.0/modulemd.h
View file
Original file line number Diff line number Diff line change
Expand Up @@ -45,36 +45,34 @@ G_BEGIN_DECLS
*
* # Working with repodata (DNF use-case) #
* The libmodulemd API provides a number of convenience tools for interacting
* with repodata (that is, streams of YAML that contains information on
* multiple streams, default data and translations). The documentation will use
* two repositories, called "fedora" and "updates" for demonstrative purposes.
* It will assume that the content of the YAML module metadata from those two
* repositories have been loaded into string variables "fedora_yaml" and
* "updates_yaml", respectively.
* with repodata (that is, streams of YAML that contains information on multiple
* streams, default data and translations). The documentation will use two
* repositories, called "fedora" and "updates" for demonstrative purposes. It
* will assume that the content of the YAML module metadata from those two
* repositories have been loaded into string variables `fedora_yaml` and
* `updates_yaml`, respectively.
*
* First step is to load the metadata from these two repositories into
* #ModulemdModuleIndex objects. This is done as follows:
*
* In C:
* |[<!-- language="C" -->
* fedora_index = modulemd_module_index_new();
* ret = modulemd_module_index_update_from_string(fedora_index,
* fedora_yaml,
* &failures,
* &error);
*
* updates_index = modulemd_module_index_new();
* ret = modulemd_module_index_update_from_string(updates_index,
* updates_yaml,
* &failures,
* &error);
* ]|
* ModulemdModuleIndex * fedora_index = modulemd_module_index_new ();
* gboolean ret = modulemd_module_index_update_from_string (fedora_index,
* fedora_yaml,
* TRUE,
* &failures,
* &error);
*
* The @failures argument will return any subdocuments in the YAML stream
* that could not be parsed or validated successfully. In the event that the
* stream as a whole could not be parsed, @error will be set accordingly.
* ModulemdModuleIndex * updates_index = modulemd_module_index_new ();
* gboolean ret2 = modulemd_module_index_update_from_string (updates_index,
* updates_yaml,
* TRUE,
* &failures,
* &error);
* ]|
*
* In python:
* In Python:
*
* |[<!-- language="Python" -->
* fedora_index = Modulemd.ModuleIndex.new()
Expand All @@ -84,17 +82,22 @@ G_BEGIN_DECLS
* ret, failures = updates_index.update_from_string(updates_yaml, True)
* ]|
*
* The @failures are a list of subdocuments in the YAML that failed parsing,
* along with the reason they failed. Hence, by checking the return value of
* @failures we will know if the YAML parsing was successful or not.
*
* Since it doesn't really make sense to view the contents from separate
* repositories in isolation (in most cases), the next step is to merge the
* two indexes into a combined one:
* repositories in isolation (in most cases), the next step is to merge the two
* indexes into a combined one:
*
* In C:
* |[<!-- language="C" -->
* merger = modulemd_module_index_merger_new()
* ModulemdModuleIndexMerger * merger = modulemd_module_index_merger_new ();
*
* modulemd_module_index_merger_associate_index (merger, fedora_index, 0);
* modulemd_module_index_merger_associate_index (merger, updates_index, 0);
*
* merged_index = modulemd_module_index_merger_resolve (merger, &error);
* ModulemdModuleIndex * merged_index = modulemd_module_index_merger_resolve (merger, &error);
* ]|
*
* In Python:
Expand All @@ -116,29 +119,90 @@ G_BEGIN_DECLS
* index will contain only v2 objects (with the v1 objects automatically
* upgraded internally).
*
* At this point, we can start operating on the retrieved data. This guide will
* Now, we can start operating on the retrieved data. This guide will
* give only a brief overview of the most common operations. See the API
* specification for a full list of information that can be retrieved.
*
* ## Discover the default stream for a particular module.
* In C:
* |[<!-- language="C" -->
* ModulemdModule * module = modulemd_module_index_get_module (merged_index, "modulename");
* ModulemdDefaults * defaults = modulemd_module_get_defaults (module);
* printf ("Default stream for modulename is %s\n",
* modulemd_defaults_v1_get_default_stream (MODULEMD_DEFAULTS_V1 (defaults), NULL));
* ]|
*
* In Python:
* |[<!-- language="Python" -->
* module = merged_index.get_module ('modulename')
* defaults = module.get_defaults()
* print ('Default stream for modulename is %s' % (
* defaults.get_default_stream())
* ]|
*
* ## Get the list of RPMs defining the public API for a particular module NSVC
*
* ## Get the list of RPMs defining the public API for a particular module NSVCA
* First, query the #ModulemdModuleIndex for the module with a given name.
*
* In C:
* |[<!-- language="C" -->
* ModulemdModule * module = modulemd_module_index_get_module (merged_index, "modulename");
* ]|
*
* In Python:
* |[<!-- language="Python" -->
* module = merged_index.get_module ('modulename')
* stream = module.get_stream_by_NSVC('modulestream', 1, 'deadbeef')
* ]|
*
* Then, query the #ModulemdModule for the #ModulemdModuleStream associated with the
* provided NSVCA (name-stream-version-context-architecture identifier).
*
* In C:
* |[<!-- language="C" -->
* ModulemdModuleStream * stream = modulemd_module_get_stream_by_NSVCA (module,
* "modulestream",
* 0,
* "deadbeef",
* "coolarch",
* &error);
* ]|
*
* In Python:
* |[<!-- language="Python" -->
* stream = module.get_stream_by_NSVCA('modulestream', 0, 'deadbeef', 'coolarch')
* ]|
*
* Lastly, read the RPM API from the #ModulemdModuleStream. Here, `api_list` is
* a list of strings containing package names.
*
* In C:
* |[<!-- language="C" -->
* GStrv api_list = modulemd_module_stream_v2_get_rpm_api_as_strv (MODULEMD_MODULE_STREAM_V2 (stream));
* ]|
*
* In Python:
* |[<!-- language="Python" -->
* api_list = stream.get_rpm_api()
* ]|
*
* ## Retrieve the modular runtime dependencies for a particular module NSVC
*
* ## Retrieve the modular runtime dependencies for a particular module NSVCA
* In C:
* |[<!-- language="C" -->
* ModulemdModule * module = modulemd_module_index_get_module (merged_index, "modulename");
* ModulemdModuleStream * stream = modulemd_module_get_stream_by_NSVCA (module, "modulestream", 0, "deadbeef", "coolarch", &error);
* GPtrArray * deps_list = modulemd_module_stream_v2_get_dependencies (MODULEMD_MODULE_STREAM_V2 (stream));
*
* for (gint i = 0; i < deps_list->len; i++)
* {
* stuff with g_ptr_array_index(deps_list, i);
* }
* ]|
*
* In Python:
* |[<!-- language="Python" -->
* module = merged_index.get_module ('modulename')
* stream = module.get_stream_by_NSVC('modulestream', 1, 'deadbeef')
* stream = module.get_stream_by_NSVCA('modulestream', 0, 'deadbeef', 'coolarch')
* deps_list = stream.get_dependencies()
*
* for dep in deps_list:
Expand All @@ -149,16 +213,16 @@ G_BEGIN_DECLS
*
* # Working with a single module stream (Packager/MBS use-case)
* One limitation of the #ModulemdModuleIndex format is that it requires that
* all module streams loaded into it have both a name and a stream name. This
* however is not possible when dealing with streams such as a packager would
* be using (since the build-system auto-generates the module name and stream
* name from the git repository information. In this case, we need to work
* with a single module stream document at a time. For this, we will use the
* #ModulemdModuleStream interface.
*
* This example will assume that the module name and stream name have already
* been determined from the repodata and that they are stored in string
* variables named 'module_name' and 'stream_name', respectively.
* all module streams loaded into it have both a name and a stream name.
* This however is not possible when dealing with streams such as a packager
* would be using (since the build-system auto-generates the module name and
* stream name from the git repository information. In this case, we need to
* work with a single module stream document at a time. For this, we will
* use the #ModulemdModuleStream interface.
*
* This example will assume that the module name and stream name have
* already been determined from the repodata and that they are stored in
* string variables named `module_name` and `stream_name`, respectively.
*
* |[<!-- language="Python" -->
* stream = Modulemd.ModuleStream.read_file ('/path/to/module_name.yaml',
Expand Down

0 comments on commit 0a42e0c

Please sign in to comment.