Hello World: Init and Version Check

A first and easy test that AML is set up properly and can be linked with a user program is to try to check that the headers and the library version match. All AML programs must also start by initializing the library and must end with a call to the cleanup function.

APIs

Setup/Teardown API

int aml_init(int *argc, char **argv[])

Initialize the library.

Parameters:

  • argc – [inout] pointer to the main()’s argc argument; contents can get modified.

  • argv – [inout] pointer to the main()’s argv argument; contents can get modified.

Returns:

0 if successful; an error code otherwise.

int aml_finalize(void)

Terminate the library.

Returns:

0 if successful; an error code otherwise.

Version API

AML defines its version using semantic versioning, with a macro and variable for each subcomponent of the version number:

  • Version major: denotes ABI changes which prevent compatibility with previous major version ABI.

  • Version minor: denotes new features or improvement without breaking the old ABI.

  • Patch version: patch and fix releases only.

The full version string is also available directly.

/* see aml/utils/version.h for details */
#define AML_VERSION_MAJOR  ...
#define AML_VERSION_MINOR  ...
#define AML_VERSION_PATCH  ...
#define AML_VERSION_STRING ...

extern const int aml_version_major    = ...;
extern const int aml_version_minor    = ...;
extern const int aml_version_patch    = ...;
extern const char *aml_version_string = ...;

Usage

Both the setup and the version APIs are available directly from the main AML header.

#include <aml.h>

Initialization is done by passing pointers to the command-line arguments of the program to the library.

int main(int argc, char **argv){
...
if(aml_init(&argc, &argv) != 0){
  fprintf(stderr, "AML library init failure!\n");
  return 1;
}

Checking that the program is linked against the same version as the one used during compilation is as easy as comparing the header version AML_VERSION_MAJOR and the library-embedded version aml_version_major.

if(aml_version_major != AML_VERSION_MAJOR){
    fprintf(stderr, "AML ABI mismatch!\n");
    return 1;
}

Exercise

Write a “hello world” code that checks both major and minor versions of the code.

Click Here to Show/Hide Code

/*******************************************************************************
 * Copyright 2019 UChicago Argonne, LLC.
 * (c.f. AUTHORS, LICENSE)
 *
 * This file is part of the AML project.
 * For more info, see https://github.com/anlsys/aml
 *
 * SPDX-License-Identifier: BSD-3-Clause
 ******************************************************************************/

#include <aml.h>
#include <stdio.h>

int
main(int argc, char **argv)
{
	if (aml_init(&argc, &argv) != AML_SUCCESS)
		return 1;

	// Detect if header match the library ABI.
	if ((aml_version_major != AML_VERSION_MAJOR) ||
	    (aml_version_minor != AML_VERSION_MINOR)) {
		fprintf(stderr, "AML version mismatch\n");
		return 1;
	}

	aml_finalize();

	fprintf(stderr, "Hello world!\n");
	return 0;
}

You can find this solution in doc/tutorials/hello_world/.