Add a comment in the examples/ folder for each example program explaining how to run it #115

examples/1-load/example_load.go

@@ -4,6 +4,7 @@
 
 // This example demonstrates loading an SPDX tag-value file from disk into
 // memory, and printing some of its contents to standard output.
+// Run project:  go run example_load.go ../../testdata/spdx-examples/example1/spdx/example1.spdx
 
 package main
 

examples/10-jsonloader/example_json_loader.go

@@ -4,7 +4,7 @@
 
 // This example demonstrates loading an SPDX json from disk into memory,
 // and then logging out some attributes to the console .
-
+// Run project: go run example_json_loader.go ../../testdata/spdx-examples/json/SPDXJSONExample-v2.2.spdx.json example.spdx
 package main
 
 import (
@@ -20,7 +20,7 @@ func main() {
 	// check that we've received the right number of arguments
 	args := os.Args
 	if len(args) != 3 {
-		fmt.Printf("Usage: %v <spdx-file-in> <spdx-file-out>\n", args[0])
+		fmt.Printf("Usage: %v <json-file-in> <spdx-file-out>\n", args[0])
 		fmt.Printf("  Load SPDX 2.2 tag-value file <spdx-file-in>, and\n")
 		fmt.Printf("  save it out to <spdx-file-out>.\n")
 		return

examples/2-load-save/example_load_save.go

@@ -4,6 +4,7 @@
 
 // This example demonstrates loading an SPDX tag-value file from disk into memory,
 // and re-saving it to a different file on disk.
+// Run project: go run example_load_save.go ../../testdata/spdx-examples/example1/spdx/example1.spdx test.spdx
 
 package main
 

examples/4-search/example_search.go

@@ -7,6 +7,7 @@
 // [SPDX short-form IDs](https://spdx.org/ids/); filling those IDs into the
 // document's Package and File license fields; and saving the resulting document
 // to disk.
+// Run project: go run example_search.go project2 ../../testdata/project2/folder test.spdx
 
 package main
 

examples/5-report/example_report.go

@@ -5,7 +5,7 @@
 // This example demonstrates loading an SPDX tag-value file from disk into memory,
 // generating a basic report listing counts of the concluded licenses for its
 // files, and printing the report to standard output.
-
+// Run project: go run example_report.go ../../testdata/spdx-examples/example1/spdx/example1.spdx
 package main
 
 import (

examples/6-licensediff/example_licensediff.go

@@ -8,7 +8,7 @@
 // This is generally only useful when run with two SPDX documents that
 // describe licenses for subsequent versions of the same set of files, AND if
 // they have the same identifier in both documents.
-
+// Run project: go run example_licensediff.go ../../testdata/spdx-examples/example1/spdx/example1.spdx ../../testdata/spdx-examples/example2/spdx/example2-src.spdx
 package main
 
 import (

examples/7-rdfloader/exampleRDFLoader.go

@@ -1,5 +1,5 @@
 // SPDX-License-Identifier: Apache-2.0 OR GPL-2.0-or-later
-
+// Run project: go run exampleRDFLoader.go ../../testdata/spdx-examples/rdf/SPDXRdfExample.rdf
 package main
 
 import (
@@ -9,20 +9,25 @@ import (
 	"strings"
 )
 
-func getFilePathFromUser() string {
+func getFilePathFromUser() (string, error) {
 	if len(os.Args) == 1 {
 		// user hasn't specified the rdf file path
-		panic("kindly provide path of the rdf file to be loaded as a spdx-document while running this file")
+		return "", fmt.Errorf("kindly provide path of the rdf file to be loaded as a spdx-document while running this file")
 	}
-	return os.Args[1]
+	return os.Args[1], nil
 }
 
 func main() {
 	// example to use the rdfLoader.
-	filePath := getFilePathFromUser()
+	filePath, ok := getFilePathFromUser()
+	if ok != nil {
+		_ = fmt.Errorf("%v", ok)
+		return
+	}
 	file, err := os.Open(filePath)
 	if err != nil {
-		panic(fmt.Errorf("error opening File: %s", err))
+		_ = fmt.Errorf("error opening File: %s", err)
+		return
 	}
 
 	// loading the spdx-document

examples/8-jsontotv/examplejsontotv.go

@@ -4,7 +4,7 @@
 
 // This example demonstrates loading an SPDX json from disk into memory,
 // and then re-saving it to a different file on disk in tag-value format .
-
+// Run project: go run examplejsontotv.go ../../testdata/spdx-examples/json/SPDXJSONExample-v2.2.spdx.json example.spdx
 package main
 
 import (
@@ -20,7 +20,7 @@ func main() {
 	// check that we've received the right number of arguments
 	args := os.Args
 	if len(args) != 3 {
-		fmt.Printf("Usage: %v <spdx-file-in> <spdx-file-out>\n", args[0])
+		fmt.Printf("Usage: %v <json-file-in> <spdx-file-out>\n", args[0])
 		fmt.Printf("  Load SPDX 2.2 tag-value file <spdx-file-in>, and\n")
 		fmt.Printf("  save it out to <spdx-file-out>.\n")
 		return

examples/9-tvtojson/exampletvtojson.go

@@ -4,7 +4,7 @@
 
 // This example demonstrates loading an SPDX tag-value file from disk into memory,
 // and re-saving it to a different json file on disk.
-
+// Run project: go run exampletvtojson.go ../../testdata/spdx-examples/example1/spdx/example1.spdx example.json
 package main
 
 import (
@@ -20,7 +20,7 @@ func main() {
 	// check that we've received the right number of arguments
 	args := os.Args
 	if len(args) != 3 {
-		fmt.Printf("Usage: %v <spdx-file-in> <spdx-file-out>\n", args[0])
+		fmt.Printf("Usage: %v <spdx-file-in> <json-file-out>\n", args[0])
 		fmt.Printf("  Load SPDX 2.2 tag-value file <spdx-file-in>, and\n")
 		fmt.Printf("  save it out to <spdx-file-out>.\n")
 		return

examples/README.md

@@ -11,21 +11,23 @@ tools-golang sub-packages.
 
 This example demonstrates loading an SPDX tag-value file from disk into memory,
 and printing some of its contents to standard output.
+#### Run project: *go run example_load.go ../../testdata/spdx-examples/example1/spdx/example1.spdx*
 
 ## 2-load-save/
 
 *tvloader*, *tvsaver*
 
 This example demonstrates loading an SPDX tag-value file from disk into memory,
 and re-saving it to a different file on disk.
-
+#### Run project: *go run example_load_save.go ../../testdata/spdx-examples/example1/spdx/example1.spdx test.spdx*
 ## 3-build/
 
 *builder*, *tvsaver*
 
 This example demonstrates building an 'empty' SPDX document in memory that
 corresponds to a given directory's contents, including all files with their
 hashes and the package's verification code, and saving the document to disk.
+#### Run project:  *go run example_build.go project2 ../../testdata/project2 test.spdx*
 
 ## 4-search/
 
@@ -35,6 +37,7 @@ This example demonstrates building an SPDX document for a directory's contents
 (implicitly using *builder*); searching through that directory for [SPDX
 short-form IDs](https://spdx.org/ids/); filling those IDs into the document's
 Package and File license fields; and saving the resulting document to disk.
+#### Run project: *go run example_search.go project2 ../../testdata/project2/folder test.spdx*
 
 ## 5-report/
 
@@ -43,7 +46,8 @@ Package and File license fields; and saving the resulting document to disk.
 This example demonstrates loading an SPDX tag-value file from disk into memory,
 generating a basic report listing counts of the concluded licenses for its
 files, and printing the report to standard output.
-
+#### Run project: * go run example_report.go ../../testdata/spdx-examples/example1/spdx/example1.spdx
+*
 ## 6-licensediff
 
 *licensediff*, *tvloader*
@@ -55,32 +59,36 @@ with matching IDs in each document.
 This is generally only useful when run with two SPDX documents that describe
 licenses for subsequent versions of the same set of files, AND if they have
 the same identifier in both documents.
-
+#### Run project *Run project: go run example_licensediff.go ../../testdata/spdx-examples/example1/spdx/example1.spdx ../../testdata/spdx-examples/example2/spdx/example2-src.spdx*
 
 ## 7-rdfloader
 
 *rdfloader*, *spdx*
 
 This example demonstrates loading an SPDX rdf file from disk into memory 
 and then printing the corresponding spdx struct for the document.
+#### Run project: *go run exampleRDFLoader.go ../../testdata/spdx-examples/rdf/SPDXRdfExample.rdf*
 
 ## 8-jsontotv
 
 *jsonloader*, *tvsaver*
 
 This example demonstrates loading an SPDX json from disk into memory
 and then re-saving it to a different file on disk in tag-value format.
+#### Run project: *go run examplejsontotv.go ../../testdata/spdx-examples/json/SPDXJSONExample-v2.2.spdx.json example.spdx*
 
 ## 9-tvtojson
 
 *jsonsaver*, *tvloader*
 
 This example demonstrates loading an SPDX tag-value from disk into memory
 and then re-saving it to a different file on disk in json format.
+#### Run project: *go run exampletvtojson.go ../../testdata/spdx-examples/example1/spdx/example1.spdx example.json*
 
 ## 10-jsonloader
 
 *jsonloader*
 
 This example demonstrates loading an SPDX json from disk into memory
 and then logging some of the attributes to the console.
+#### Run project: *go run example_json_loader.go ../../testdata/spdx-examples/json/SPDXJSONExample-v2.2.spdx.json example.spdx*

testdata/spdx-examples/example1/README.md

@@ -0,0 +1,33 @@
+# Example 1
+
+## Description
+
+```
+content
+├── build
+│   └── hello
+└── src
+    ├── Makefile
+    └── hello.c
+```
+
+One [C source file](content/src/hello.c) with a simple "hello world" program, compiled into a [single binary](content/build/hello) with no dependencies via a [Makefile](content/src/Makefile).
+(Assumed dependencies such as the operating system kernel, C standard library, etc. are not addressed here.)
+
+One [SPDX document](spdx/example1.spdx) showing the Makefile, source file and binary, together as a single package.
+
+This assumes of course that all three files are in fact being distributed together as a single package.
+
+## Comments
+
+The `DESCRIBES` relationship near the top of the file is not mandatory in this case, because there is only a single Package in this document.
+(See the `DESCRIBES` relationship in [Section 7.1](https://spdx.github.io/spdx-spec/7-relationships-between-SPDX-elements/) of the spec.)
+
+The three relationships at the end of the document (`GENERATED_FROM` and `BUILD_TOOL_OF`) are also not mandatory.
+They are included here to demonstrate how SPDX can be used to communicate that a binary is built from particular source files and build tools.
+
+The `SPDXID` for each Package and File does not have to be something that would be meaningful to a human reader, if generated by a tool and/or intended for consumption primarily by a tool.
+They could just as easily have been `SPDXRef-File0`, `SPDXRef-File1`, etc.
+(In fact, that's what they originally were from the tool that generated this SPDX document, but they have been given clearer identifiers here for ease of understanding.)
+
+FileType fields were also added in manually and are not mandatory.

testdata/spdx-examples/example1/content/src/Makefile

@@ -0,0 +1,10 @@
+# SPDX-License-Identifier: GPL-3.0-or-later
+
+example1: hello.c
+	gcc -o ../build/hello hello.c
+
+.PHONY: clean
+
+clean:
+	rm ../build/hello
+

testdata/spdx-examples/example1/content/src/hello.c

@@ -0,0 +1,17 @@
+/* SPDX-License-Identifier: GPL-3.0-or-later */
+/* Copyright Contributors to the spdx-examples project. */
+
+/*
+ * Example 1
+ *
+ * Just a single C file with a simple "Hello world" program.
+ *
+ */
+
+#include <stdio.h>
+
+int main(int argc, char *argv[]) {
+	printf("Hello world!\n");
+	return 0;
+}
+

testdata/spdx-examples/example1/spdx/example1.spdx

@@ -0,0 +1,57 @@
+SPDXVersion: SPDX-2.2
+DataLicense: CC0-1.0
+SPDXID: SPDXRef-DOCUMENT
+DocumentName: hello
+DocumentNamespace: https://swinslow.net/spdx-examples/example1/hello-v3
+Creator: Person: Steve Winslow (steve@swinslow.net)
+Creator: Tool: github.com/spdx/tools-golang/builder
+Creator: Tool: github.com/spdx/tools-golang/idsearcher
+Created: 2021-08-26T01:46:00Z
+
+##### Package: hello
+
+PackageName: hello
+SPDXID: SPDXRef-Package-hello
+PackageDownloadLocation: git+https://github.com/swinslow/spdx-examples.git#example1/content
+FilesAnalyzed: true
+PackageVerificationCode: 9d20237bb72087e87069f96afb41c6ca2fa2a342
+PackageLicenseConcluded: GPL-3.0-or-later
+PackageLicenseInfoFromFiles: GPL-3.0-or-later
+PackageLicenseDeclared: GPL-3.0-or-later
+PackageCopyrightText: NOASSERTION
+
+Relationship: SPDXRef-DOCUMENT DESCRIBES SPDXRef-Package-hello
+
+FileName: /build/hello
+SPDXID: SPDXRef-hello-binary
+FileType: BINARY
+FileChecksum: SHA1: 20291a81ef065ff891b537b64d4fdccaf6f5ac02
+FileChecksum: SHA256: 83a33ff09648bb5fc5272baca88cf2b59fd81ac4cc6817b86998136af368708e
+FileChecksum: MD5: 08a12c966d776864cc1eb41fd03c3c3d
+LicenseConcluded: GPL-3.0-or-later
+LicenseInfoInFile: NOASSERTION
+FileCopyrightText: NOASSERTION
+
+FileName: /src/Makefile
+SPDXID: SPDXRef-Makefile
+FileType: SOURCE
+FileChecksum: SHA1: 69a2e85696fff1865c3f0686d6c3824b59915c80
+FileChecksum: SHA256: 5da19033ba058e322e21c90e6d6d859c90b1b544e7840859c12cae5da005e79c
+FileChecksum: MD5: 559424589a4f3f75fd542810473d8bc1
+LicenseConcluded: GPL-3.0-or-later
+LicenseInfoInFile: GPL-3.0-or-later
+FileCopyrightText: NOASSERTION
+
+FileName: /src/hello.c
+SPDXID: SPDXRef-hello-src
+FileType: SOURCE
+FileChecksum: SHA1: 20862a6d08391d07d09344029533ec644fac6b21
+FileChecksum: SHA256: b4e5ca56d1f9110ca94ed0bf4e6d9ac11c2186eb7cd95159c6fdb50e8db5a823
+FileChecksum: MD5: 935054fe899ca782e11003bbae5e166c
+LicenseConcluded: GPL-3.0-or-later
+LicenseInfoInFile: GPL-3.0-or-later
+FileCopyrightText: Copyright Contributors to the spdx-examples project.
+
+Relationship: SPDXRef-hello-binary GENERATED_FROM SPDXRef-hello-src
+Relationship: SPDXRef-hello-binary GENERATED_FROM SPDXRef-Makefile
+Relationship: SPDXRef-Makefile BUILD_TOOL_OF SPDXRef-Package-hello

testdata/spdx-examples/example2/README.md

@@ -0,0 +1,36 @@
+# Example 2
+
+## Description
+
+```
+content
+├── build
+│   └── hello
+└── src
+    ├── Makefile
+    └── hello.c
+```
+
+The content is identical to [example1](../example1): one [C source file](content/src/hello.c) with a simple "hello world" program, compiled into a [single binary](content/build/hello) with no dependencies via a [Makefile](content/src/Makefile).
+
+However, where example1 had a single SPDX document containing both source and binary, example2 instead has separate SPDX documents for [source](spdx/example2-src.spdx) and [binary](spdx/example2-bin.spdx).
+
+This describes a scenario where binary and source are distributed separately, but where we want to be able to reflect the relationships between binary and source packages.
+
+## Comments
+
+Substantively, this is the same software as in [example1](../example).
+However, here we are representing the sources and binaries as two separate Packages, on the assumption that we're distributing them separately.
+Because of this, the source Package and binary Package are described in two separate SPDX documents.
+
+Note that these do not _have_ to be in separate documents.
+A single SPDX document can contain multiple Packages.
+However, because the assumption in this scenario is that the binaries and the sources are distributed separately, it makes sense here that separate SPDX documents could accompany the binaries and the sources.
+
+Relationships across separate documents are handled via `DocumentRef-` tags, defined via external document references in the Document Creation Info section.
+Note that these external document references and relationships cannot be circular: one document can refer to the other, but (to my knowledge) they cannot refer circularly to each other.
+To reference another document in an ExternalDocumentRef definition, you need to specify its hash, so it isn't possible for two documents to refer to one another; each would need to modify its own contents based on the other's hash value.
+
+In the [SPDX document for the binary](spdx/example2-bin.spdx), note how the Relationships at the end of the document include `DocumentRef-hello-src:` as a prefix.
+This uses the `DocumentRef-` defined in the `ExternalDocumentRef` tag at the top of the document.
+This is the mechanism used to refer to SPDX identifiers for elements defined in other SPDX documents.

testdata/spdx-examples/example2/content/src/Makefile

@@ -0,0 +1,10 @@
+# SPDX-License-Identifier: GPL-3.0-or-later
+
+example1: hello.c
+	gcc -o ../build/hello hello.c
+
+.PHONY: clean
+
+clean:
+	rm ../build/hello
+