OmniBOR Specification, Version 0.1 Annex C – Source Embedding

Annex C contains a method of embedding an Input Manifest Identifier into source code files.

Embedded Input Manifest Identifier

Most source code files are hand coded by humans. Some however are generated from other input(s) by a build tool.

A build tool outputing a source code file may embed the Input Manifest Identifier for the output source code file into the output source code file by adding a comment line containing a string of the form:

OmniBOR-Input-Manifest-ID: [ ${comma separated list of Input Manifest Identifier URIs} ]

For a file with C commenting semantics (like C, C++, Java, Go, etc) a concrete example might be:

// OmniBOR-Input-Manifest-ID: [ gitoid:blob:sha1:261eeb9e9f8b2b4b0d119366dda99c6fd7d35c64, gitoid:blob:sha256:09c825ac02df9150e4f93d12ba1da5d1ff5846c3e62503c814aa3a300c535772 ]

For a file with shell commenting semantics (like a shell script, Python, etc) a concrete example might be:

# OmniBOR-Input-Manifest-ID: [ gitoid:blob:sha1:261eeb9e9f8b2b4b0d119366dda99c6fd7d35c64, gitoid:blob:sha256:09c825ac02df9150e4f93d12ba1da5d1ff5846c3e62503c814aa3a300c535772 ]

When interpretting an OmniBOR-Input-Manifest-ID comment line a reader should ignore any leading and trailing spaces around '[' or ']' or ','.

Placement of OmniBOR-Input-Manifest-ID Comment Line

The OmniBOR-Input-Manifest-ID comment line should be placed as the last line in the source code file. The OmniBOR-Input-Manifest-ID comment line should be preceded by a blank line to ensure it is not interpretted as part of another comment block.

A tool reading the source code file should interpret the last OmniBOR-Input-Manifest-ID comment line it encounters in the file as being the Input Manifest Identifier, and ignore previous comment lines in the file which may contain Input Manifest Identifiers.

Example:

If the input source code file begins with:

// Code generated by stringer DO NOT EDIT.

import (
    "fmt"
)
...

The output source code file should look like:

// Code generated by stringer DO NOT EDIT.

import (
    "fmt"
)
...

// OmniBOR-Input-Manifest-ID: [ gitoid:blob:sha1:261eeb9e9f8b2b4b0d119366dda99c6fd7d35c64, gitoid:blob:sha256:09c825ac02df9150e4f93d12ba1da5d1ff5846c3e62503c814aa3a300c535772 ]

If the input source code file begins with:

/*
 * Copyright 2023 Yoyodyne Inc
 * SPDX-License-Identifier:
 */

#include <stdio.h>
int main() {
   // printf() displays the string inside quotation
   printf("Hello, World!");
   return 0;
}

The output source code file should look like:

/*
 * Copyright 2023 Yoyodyne Inc
 * SPDX-License-Identifier:
 */

#include <stdio.h>
int main() {
   // printf() displays the string inside quotation
   printf("Hello, World!");
   return 0;
}

//* OmniBOR-Input-Manifest-ID: [ gitoid:blob:sha1:261eeb9e9f8b2b4b0d119366dda99c6fd7d35c64, gitoid:blob:sha256:09c825ac02df9150e4f93d12ba1da5d1ff5846c3e62503c814aa3a300c535772 ] */

Tools which mutate existing source code files

Many source code generation tools, like patch, specifically mutate an existing input source code file which may contain an existing OmniBOR-Input-Manifest comment. In such circumstances the tool should either

  1. Replace an existing OmniBOR-Input-Manifest comment if found
  2. Insert the OmniBOR-Input-Manifest normally, which will cause it to be placed after the existing OmniBOR-Input-Manifest comment line.