add create prototype

vsoch · vsoch · commit c4991c4dcd52 · 2024-01-25T15:59:46.000-07:00
Signed-off-by: vsoch &lt;vsoch@users.noreply.github.com&gt;
diff --git a/README.md b/README.md
@@ -3,183 +3,9 @@
 ![img/compspec.png](img/compspec.png)
 
 This is a prototype compatibility checking tool. Right now our aim is to use in the context of
-[these build matrices](https://github.com/rse-ops/lammps-matrix) for LAMMPS and these prototype [specifications](https://github.com/supercontainers/compspec) that are based off of [Proposal C](https://github.com/opencontainers/wg-image-compatibility/pull/8) of the Compatibility Working Group. This is experimental because all of that is subject (and likely) to change.
-
-## Design
-
-The design is based on the prototype from that pull request, shown below.
-
-![img/proposal-c-plugin-design.png](img/proposal-c-plugin-design.png)
-
-Specifically, I'll try to do simple interfaces (in [plugins](plugins)) to:
-
- - **Extract** Scan a system to collect compatibility metadata / attributes for a named set of extractions
-   - this maybe isn't great practice, but if I build the containers I trust them
-   - I can also do something simple like run this tool in a pod-> container small cluster
- - load in an artifact spec (json) from a URL
- - compare with a request for a specific system (with any level of detail desired)
-   - "basic" might just be providing the architecture
-   - "descriptive" might include other variables
-
-The extraction step is also important, but likely this would happen at build time (maybe by another tool).
-For now (since this is a prototype) I'm going to just manually do it.
-
-## Usage
-
-### Build
-
-Build the `compspec` binary with:
-
-```bash
-make
-```
-
-This generates the `bin/compspec` that you can use:
-
-```bash
-./bin/compspec
-```
-```console
-┏┏┓┏┳┓┏┓┏┏┓┏┓┏
-┗┗┛┛┗┗┣┛┛┣┛┗ ┗
-          ┛  ┛    
-
-[sub]Command required
-usage: compspec <Command> [-h|--help] [-n|--name "<value>" [-n|--name "<value>"
-                ...]]
-
-                Compatibility checking for container images
-
-Commands:
-
-  version  See the version of compspec
-  extract  Run one or more extractors
-
-Arguments:
-
-  -h  --help  Print help information
-  -n  --name  One or more specific extractor plugin names
-```
-
-
-### Version
-
-```bash
-$ ./bin/compspec version
-```
-```console
-⭐️ compspec version 0.1.0-draft
-```
-
-I know, the star should not be there. Fight me.
-
-### List
-
-The list command lists each extractor, and sections available for it.
-
-```bash
-$ ./bin/compspec list
-```
-```console
- Compatibility Plugins               
-        TYPE      NAME     SECTION   
-        extrator  kernel   boot      
-        extrator  kernel   config    
-        extrator  kernel   modules   
-        extrator  system   cpu       
-        extrator  system   processor 
-        extrator  system   os        
-        extrator  library  mpi       
- TOTAL  7                            
-```
-
-Note that we will eventually add a description column - it's not really warranted yet!
-
-### Extract
-
-If you want to extract metadata to your local machine, you can use extract! Either just run all extractors and dump to the terminal:
-
-```bash
-# Not recommend, it's a lot!
-./bin/compspec extract
-```
-
-Or target a specific one:
-
-```bash
-./bin/compspec extract --name kernel
-```
-
-Better, save to json file:
-
-```bash
-./bin/compspec extract --name kernel -o test-kernel.json
-```
-
-This has a better structure for inspecting easily (only the top of the file is shown):
-
-<details>
-
-<summary>Kernel JSON output</summary>
-
-```json
-{
-  "extractors": {
-    "kernel": {
-      "sections": {
-        "boot": {
-          "BOOT_IMAGE": "/boot/vmlinuz-6.1.0-1028-oem",
-          "quiet": "",
-          "ro": "",
-          "root": "UUID",
-          "splash": "",
-          "vt.handoff": "7"
-        },
-        "config": {
-          "CONFIG_104_QUAD_8": "m",
-          "CONFIG_60XX_WDT": "m",
-          "CONFIG_64BIT": "y",
-          "CONFIG_6LOWPAN": "m"
-        }
-      }
-    }
-  }
-}
-```
-
-</details>
-
-An extractor is made up of sections, and you can ask for parsing just a specific one. 
-
-```bash
-./bin/compspec extract --name kernel[config]
-```
-```console
-⭐️ Running extract...
- --Result for kernel
- -- Section boot
-   root: UUID
-   ro: 
-   quiet: 
-   splash: 
-   vt.handoff: 7
-   BOOT_IMAGE: /boot/vmlinuz-6.1.0-1028-oem
-Extraction has run!
-```
-
-To ask for more than one, it's a comma separated list.
-
-```bash
-./bin/compspec extract --name kernel[config,boot]
-```
-
-The ordering of your list is honored.
-
-## Developer
-
-Note that there is a [developer environment](.devcontainer) that provides a consistent version of Go, etc.
-However, it won't work with all extractors.  Note that for any command that uses a plugin (e.g., `extract` and `check`)
+[these build matrices](https://github.com/rse-ops/lammps-matrix) for LAMMPS and these prototype [specifications](https://github.com/supercontainers/compspec) that are based off of [Proposal C](https://github.com/opencontainers/wg-image-compatibility/pull/8) of the Compatibility Working Group. This is experimental because all of that is subject (and likely) to change. This project is under development, and you can see our [docs](docs) for early documentation.
 
+ - ⭐️ [Documentation](docs) ⭐️
 
 ### Limitations
 
@@ -188,6 +14,8 @@ However, it won't work with all extractors.  Note that for any command that uses
 
 ## TODO
 
+ - metadata namespace and exposure: someone writing a spec to create an artifact needs to know the extract namespace (and what is available) for the mapping.
+ - tests: matrix that has several different flavors of builds, generating compspec json output to validate generation and correctness
  - likely we want a common configuration file to take an extraction -> check recipe
  - need to develop check plugin family
  - todo thinking around manifest.yaml that has listing of images / artifacts
@@ -197,16 +25,8 @@ However, it won't work with all extractors.  Note that for any command that uses
 A `*` indicates required for the work / prototype I want to do
 
  - power usage data [valorium](https://ipo.llnl.gov/sites/default/files/2023-08/Final_variorum-rnd-100-award.pdf)
- - * architecture [archspec](https://github.com/archspec)
- - * MPI existence / variants
- - * operating system stuff
  - ... please add more!
 
-
-## Thanks and Previous Art
-
-- I learned about kernel parsing from [mfranczy/compat](https://github.com/mfranczy/compat)
-
 ## License
 
 This repository contains code derived from [sysinfo](https://github.com/zcalusic/sysinfo/tree/30169cfb37112a562cbf9133494a323764ad852c)
diff --git a/cmd/compspec/compspec.go b/cmd/compspec/compspec.go
@@ -7,6 +7,7 @@ import (
 
 	"github.com/akamensky/argparse"
 	"github.com/supercontainers/compspec-go/cmd/compspec/extract"
+	"github.com/supercontainers/compspec-go/cmd/compspec/create"
 	"github.com/supercontainers/compspec-go/cmd/compspec/list"
 	"github.com/supercontainers/compspec-go/pkg/types"
 )
@@ -30,12 +31,14 @@ func main() {
 	versionCmd := parser.NewCommand("version", "See the version of compspec")
 	extractCmd := parser.NewCommand("extract", "Run one or more extractors")
 	listCmd := parser.NewCommand("list", "List plugins and known sections")
+	createCmd := parser.NewCommand("create", "Create a compatibility artifact for the current host according to a definition")
 
 	// Shared arguments (likely this will break into check and extract, shared for now)
 	pluginNames := parser.StringList("n", "name", &argparse.Options{Help: "One or more specific plugins to target names"})
 
 	// Extract arguments
 	filename := extractCmd.String("o", "out", &argparse.Options{Help: "Save extraction to json file"})
+	specname := createCmd.String("i", "in", &argparse.Options{Help: "Input yaml that contains spec for creation"})
 
 	// Now parse the arguments
 	err := parser.Parse(os.Args)
@@ -50,6 +53,8 @@ func main() {
 		if err != nil {
 			log.Fatalf("Issue with extraction: %s", err)
 		}
+	} else if createCmd.Happened() {
+		create.Run(*specname)	
 	} else if listCmd.Happened() {
 		list.Run(*pluginNames)
 	} else if versionCmd.Happened() {
diff --git a/cmd/compspec/create/create.go b/cmd/compspec/create/create.go
@@ -0,0 +1,6 @@
+package create
+
+// Run will create a compatibility artifact based on a request in YAML
+func Run(specname string) error {
+	return nil
+}
diff --git a/cmd/compspec/list/list.go b/cmd/compspec/list/list.go
@@ -4,7 +4,7 @@ import (
 	p "github.com/supercontainers/compspec-go/plugins"
 )
 
-// Run will run an extraction of host metadata
+// Run will list the extractor names and sections known
 func Run(pluginNames []string) error {
 	// parse [section,...,section] into named plugins and sections
 	// return plugins
diff --git a/docs/README.md b/docs/README.md
@@ -0,0 +1,12 @@
+# Compspec Go
+
+This is early documentation that will be converted eventually to something prettier. Read more about:
+
+ - [Design](design.md)
+ - [Usage](usage.md)
+
+
+## Thanks and Previous Art
+
+- I learned about kernel parsing from [mfranczy/compat](https://github.com/mfranczy/compat)
+
diff --git a/docs/design.md b/docs/design.md
@@ -0,0 +1,55 @@
+# Design
+
+The compatibility tool is responsible for extracting information about a system, and comparing the host metadata to a contender container image to determine if it is compatible. This is a two step process that includes:
+
+1. Extracting metadata about the container image at build time
+2. Extracting metadata about the host at image selection time, and comparing against a set of contender container images to select the best one.
+
+## Definitions
+
+### Extractor
+
+An **extractor** is a core plugin that knows how to retrieve metadata about a host. An extractor is ususally going to be run for two cases:
+
+1. During CI to extract (and save) metadata about a particular build to put in a compatibility artifact.
+2. During image selection to extract information about the host to compare to.
+
+Examples extractors could be "library" or "system."
+
+### Section
+
+A **section** is a group of metadata within an extractor. For example, within "library" a section is for "mpi." This allows a user to specify running the `--name library[mpi]` extractor to ask for the mpi section of the library family. Another example is under kernel.
+The user might want to ask for more than one group to be extracted and might ask for `--name kernel[boot,config]`. Section basically provides more granularity to an extractor namespace. For the above two examples, the metadata generated would be organized like:
+
+```
+library
+   mpi.<attribute>
+kernel
+  config.<attribute>
+  boot.<attribute>
+```
+
+For the above, right now I am implementing extractors generally, or "wild-westy" in the sense that the namespace is oriented toward the extractor name and sections it owns (e.g., no community namespaces like archspec, spack, opencontainers, etc). This is subject to change depending on the design the working group decides on.
+
+### Creator
+
+A creator is a plugin that is responsible for creating an artifact that includes some extracted metadata. The creator is agnostic to what it it being asked to generate in the sense that it just needs a mapping. The mapping will be from the extractor namespace to the compatibility artifact namespace. For our first prototype, this just means asking for particular extractor attributes to map to a set of annotations that we want to dump into json. To start there should only be one creator plugin needed, however if there are different structures of artifacts needed, I could imagine more. An example creation specification for a prototype experiment where we care about architecture, MPI, and GPU is provided in [examples](examples).
+
+## Overview
+
+The design is based on the prototype from that pull request, shown below.
+
+![img/proposal-c-plugin-design.png](img/proposal-c-plugin-design.png)
+
+Specifically, I'll try to do simple interfaces (in [plugins](plugins)) to:
+
+ - **Extract** Scan a system to collect compatibility metadata / attributes for a named set of extractions
+   - this maybe isn't great practice, but if I build the containers I trust them
+   - I can also do something simple like run this tool in a pod-> container small cluster
+ - load in an artifact spec (json) from a URL
+ - compare with a request for a specific system (with any level of detail desired)
+   - "basic" might just be providing the architecture
+   - "descriptive" might include other variables
+
+The extraction step is also important, but likely this would happen at build time (maybe by another tool).
+For now (since this is a prototype) I'm going to just manually do it.
diff --git a/docs/img/proposal-c-plugin-design.png b/docs/img/proposal-c-plugin-design.png
diff --git a/docs/usage.md b/docs/usage.md
diff --git a/examples/lammps-experiment.yaml b/examples/lammps-experiment.yaml

Original file line number	Diff line number	Diff line change
`@@ -4,7 +4,7 @@ import (`
`4`	`4`	`p "github.com/supercontainers/compspec-go/plugins"`
`5`	`5`	`)`
`6`	`6`
`7`		`-// Run will run an extraction of host metadata`
	`7`	`+// Run will list the extractor names and sections known`
`8`	`8`	`func Run(pluginNames []string) error {`
`9`	`9`	`// parse [section,...,section] into named plugins and sections`
`10`	`10`	`// return plugins`