github.com/ActiveState/cli@v0.0.0-20240508170324-6801f60cd051/pkg/platform/runtime/envdef/doc.go (about)

     1  // Package envdef implements a parser for the runtime environment for alternative builds
     2  //
     3  // Builds that are built with the alternative build environment, include
     4  // runtime.json files that define which environment variables need to be set to
     5  // install and use the provided artifacts.
     6  // The schema of this file can be downloaded [here](https://drive.google.com/drive/u/0/my-drive)
     7  //
     8  // The same parser and interpreter also exists in [TheHomeRepot](https://github.com/ActiveState/TheHomeRepot/blob/master/service/build-wrapper/wrapper/runtime.py)
     9  //
    10  // Changes to the runtime environment definition schema should be synchronized
    11  // between these two places. For now, this can be most easily accomplished by
    12  // keeping the description of test cases in the [cli repo](https://github.com/ActiveState/cli/blob/master/pkg/platform/runtime/envdef/runtime_test_cases.json)
    13  // and [TheHomeRepot](https://github.com/ActiveState/TheHomeRepot/blob/master/service/build-wrapper/runtime_test_cases.json)
    14  // in sync.
    15  //
    16  // Examples:
    17  //
    18  // ## Define a PATH and LD_LIBRARY_PATH variable
    19  //
    20  // Assuming the runtime is installed to a directory `/home/user/.cache/installdir`,
    21  // the following definition asks to set the PATH variables to
    22  // `/home/user/.cache/installdir/bin:/home/user/.cache/installdir/usr/bin` and
    23  // `LD_LIBRARY_PATH` to
    24  // `/home/user/.cache/installdir/lib`
    25  // The set `inherit` flag on the `PATH` variable ensures that the `PATH` value
    26  // is prepended to the existing `PATH` that is already set in the environment.
    27  //
    28  // ```json
    29  // {
    30  //	"env": [{
    31  //		    "env_name": "PATH",
    32  //		    "values": ["${INSTALLDIR}/bin", "${INSTALLDIR}/usr/bin"],
    33  //		    "join": "prepend",
    34  //		    "inherit": true,
    35  //          "separator": ":"
    36  //		}, {
    37  //			"env_name": "LD_LIBRARY_PATH",
    38  //			"values": ["${INSTALLDIR}/lib"],
    39  //			"join": "prepend",
    40  //			"inherit": false,
    41  //          "separator": ":"
    42  //		}],
    43  //    "installdir": "installdir"
    44  // }
    45  // ```
    46  //
    47  // The installdir is used during the unpacking step to identify the directory
    48  // inside the artifact tarball that needs to be unpacked to `/home/user/.cache/installdir`
    49  //
    50  // ## Joining two definitions
    51  //
    52  // Assume we have a second environment definition file exists with the following contents:
    53  //
    54  // ```json
    55  // {
    56  //	"env": [{
    57  //		    "env_name": "PATH",
    58  //		    "values": ["${INSTALLDIR}/bin", "${INSTALLDIR}/usr/local/bin"],
    59  //		    "join": "prepend",
    60  //		    "inherit": true,
    61  //          "separator": ":"
    62  //		}, {
    63  //			"env_name": "LD_LIBRARY_PATH",
    64  //			"values": ["${INSTALLDIR}/lib", "${INSTALLDIR}/lib64"],
    65  //			"join": "prepend",
    66  //			"inherit": false,
    67  //          "separator": ":"
    68  //		}],
    69  //    "installdir": "installdir"
    70  // }
    71  // ```
    72  //
    73  // Merging this environment definition into the previous one sets
    74  // the `PATH` to `/home/user/.cache/installdir/bin:/home/user/.cache/installdir/usr/local/bin:/home/user/.cache/installdir/usr/bin`.
    75  // Note, that duplicate values are filtered out.
    76  // Likewise the `LD_LIBRARY_PATH` will end up as `/home/user/.cache/installdir/lib:/home/user/.cache/installdir/lib64`
    77  //
    78  // In this example, the values were joined by prepending the second definition
    79  // to the first.
    80  // Other join strategies are `append` and `disallowed`.
    81  //
    82  // The `disallowed` join strategy can be used if a variable should have only ONE
    83  // value, and this value needs to be the same or undefined between all artifacts
    84  // that depend on it.
    85  //
    86  // ## Usage
    87  //
    88  // - Environment definition files can be parsed from a file with the `NewEnvironmentDefinition()` function.
    89  // - Two environment definitions `ed1` and `ed2` can be merged like so:
    90  //     ed1.Merge(ed2)
    91  // - Once the installation directory is specified, the variable values can be expanded:
    92  //     ed.ExpandVariables("/home/user/.cache/installdir")
    93  package envdef