From f7cb8fe6cf93148a7dfbacbf4222f9388faad050 Mon Sep 17 00:00:00 2001 From: Liam Waldron Date: Mon, 11 Nov 2024 15:05:34 -0500 Subject: [PATCH] 11/11 - update libglacier documentation --- docs/libglacier.html | 236 ++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 235 insertions(+), 1 deletion(-) diff --git a/docs/libglacier.html b/docs/libglacier.html index 8843c0b..dbd4dcc 100644 --- a/docs/libglacier.html +++ b/docs/libglacier.html @@ -50,13 +50,247 @@

libglacier is provided as a static library only.

If you wish to compile a shared library instead, you must edit the Makefile

+

3 - Using libglacier in a program

+

To use libglacier in a program, include the relevant header files:

+ CODE: Including libglacier header files +
+

#include <glacier_config.h>

+

#include <glacier_data.h>

+

#include <glacier_log.h>

+

#include <glacier_pkgops.h>

+

#include <glacier_runtime.h>

+
+

+

To compile libglacier into your program, add the following compile flag:

+

-lconfig

+

+

4 - Configuration Functions

+

libglacier supplies functions for parsing and getting values from libconfig-syntax configuration files. While only three are present, more are planned for the future.

+

4.1 init_config

+

init_config initializes the libconfig library, and allows configuration files to be parsed.

+

No parameters are accepted by init_config.

+ CODE: init_config used in a program +
+

#include <glacier_config.h>

+

 

+

int

+

main()

+

{

+

        init_config();

+

}

+
+

init_config returns 0 on success, and 1 on failure.

+

+

4.2 die_config

+

die_config unloads the libconfig library. You should always run this when you're finished with libconfig in order to free memory.

+

No parameters are accepted by die_config.

+ CODE: die_config used in a program +
+

#include <glacier_config.h>

+

 

+

int

+

main()

+

{

+

        die_config();

+

}

+
+

die_config returns 0 on success, and 1 on failure.

+

4.3 load_all_from_config

+

load_all_from_config loads all expected settings from /etc/glacier.cfg.

+

No parameters are accepted by load_all_from_config.

+ CODE: load_all_from_config used in a program +
+

#include <glacier_config.h>

+

 

+

int

+

main()

+

{

+

        init_config();

+

}

+
+

5 - Data structure functions

+

Since Glacier is a package manager, libglacier provides functions for creating and handling dependency trees.

+

5.1 create_node

+

create_node creates a node for a dependency tree.

+

create_node accepts the following parameters:

+ + CODE: create_node used in a program +
+

#include <glacier_data.h>

+

 

+

int

+

main()

+

{

+

        struct node package = create_node("Package");

+

}

+
+

5.2 add_child

+

add_child adds a specified child node to a parent node.

+

add_child accepts the following parameters:

+ + CODE: add_child used in a program +
+

#include <glacier_data.h>

+

 

+

int

+

main()

+

{

+

        struct node pack = create_node("pack"); +

        struct node dep1 = create_node("dep1"); +

        add_child(pack, dep1);

+

}

+
+

5.3 print_tree

+

print_tree prints a dependency tree specified at its root node.

+

print_tree accepts the following parameters:

+ + CODE: print_tree used in a program +
+

#include <glacier_data.h>

+

 

+

int

+

main()

+

{

+

        struct node pack = create_node("pack");

+

        struct node dep1 = create_node("dep1");

+

        add_child(pack, dep1);

+

        print_tree(pack, 0);

+

}

+
+

+

6 - Logging Functions

+

The logging functions libglacier provides are designed to allow a uniform style of output.

+

The following logging functions are included:

+ +

These four functions accept the following parameters:

+ +

+ NOTE: +
+

Logging functions do not require a newline character ('\n'), they will automatically place one after the message.

+
+

+ CODE: Logging functions used in a program +
+

#include <glacier_log.h>

+

 

+

int

+

main()

+

{

+

        infolog("This is an info message");

+

        warnlog("This is a warning message");

+

        errlog("This is an error message");

+

        successlog("This is a success message");

+

}

+
+

+

7 - Package Operation Functions

+

This section describes the numerous functions related to operations on packages.

+

7.1 mkworkspace

+

mkworkspace creates a Glacier workspace at /tmp/glacier-workspace.

+

mkworkspace accepts no parameters.

+

mkworkspace returns the following values:

+ + CODE: mkworkspace used in a program +
+

#include <glacier_pkgops.h>

+

 

+

int

+

main()

+

{

+

        mkworkspace();

+

}

+
+

7.2 prepare_pkg

+

prepare_pkg copies a package archive from the local package database to the workspace, and untars it.

+

prepare_pkg accepts the following parameters:

+ +

prepare_pkg returns the following values:

+ + CODE: prepare_pkg used in a program +
+

#include <glacier_pkgops.h>

+

 

+

int

+

main()

+

{

+

        prepare_pkg("/glacier/localdb/epkgs-x86_64-musl/foo.tar");

+

}

+
+

 

+ CAUTION: +
+

This example presented is not the best. Instead of manually specifying the package directory, you should be calling the system profile.

+
+

7.3 run_make_task

+

run_make_task runs a specified make task in a package's current working directory.

+

run_make_task accepts the following parameters:

+ +

run_make_task returns the following values:

+ + CODE: run_make_task used in a program +
+

#include <glacier_pkgops.h>

+

 

+

int

+

main()

+

{

+

        prepare_pkg("/glacier/localdb/epkgs-x86_64-musl/foo.tar");

+

        run_make_task("installpkg");

+

}

+
+

8 - Runtime Functions

+

The functions described here are used for various runtime checks.

+

8.1 runtime_exists

+

runtime_exists checks if necessary runtime files exist and are in their correct locations.

+

runtime_exists accepts no parameters. +

runtime_exists returns no values.

+ CODE: runtime_exists used in a program +
+

#include <glacier_runtime.h>

+

 

+

int

+

main()

+

{

+

        runtime_exists();

+

}

+
+

8.2