From a88cc3146c444d8e3bc7b7e0dc7e44b82c8a16b1 Mon Sep 17 00:00:00 2001
From: tobias <tobiaskessels@cydefex.de>
Date: Wed, 10 Jun 2026 14:34:11 +0200
Subject: [PATCH] docs: add verified build instructions; fix bincmp ssdeep API

- README "Building From Source" section covering all Go and Rust tools;
  every command tested (rustc, go build, goipgrep make build/test)
- bincmp: ssdeep.HashFromFile does not exist in pinned ssdeep v0.4.0,
  switch to FuzzyFilename; fix two go vet warnings
- ignore in-place build outputs for bincmp/gopname/goinfo

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 .gitignore                           |  3 ++
 README.md                            | 42 ++++++++++++++++++++++++++++
 projects/go-tools/bincmp/gobincmp.go | 16 +++++------
 3 files changed, 53 insertions(+), 8 deletions(-)

diff --git a/.gitignore b/.gitignore
index d90a6c0..0a1fc68 100644
--- a/.gitignore
+++ b/.gitignore
@@ -15,5 +15,8 @@ bin/
 .ruff_cache/
 
 # compiled binaries that live next to their source
+projects/go-tools/bincmp/bincmp
+projects/go-tools/gopname/gopname
+projects/go-tools/goinfo/goinfo
 projects/go-tools/gosoft/gosoft
 archive/experimental/go/tarsum/tarsum
diff --git a/README.md b/README.md
index 2d52f94..8cec336 100644
--- a/README.md
+++ b/README.md
@@ -302,6 +302,48 @@ All Go code lives under `projects/go-tools/` (one directory per tool).
 - `projects/puzzlebox/`: puzzle-solving and voxel-based search experiments with several solver variants.
 - `projects/timesketch/deploy_timesketch.sh`: deployment helper for Timesketch.
 
+## Building From Source
+
+No compiled binaries are checked in — everything is built from source on demand.
+All commands below were verified to work; the Python tools in `tools/` need no build step.
+
+Go tools with a `go.mod` (build from inside the tool directory so the module is picked up):
+
+```sh
+cd projects/go-tools/bincmp  && go build -o bincmp .     # fuzzy binary/dir comparison
+cd projects/go-tools/gopname && go build -o gopname .    # process-title demo
+cd projects/go-tools/goinfo  && go build -o goinfo .     # file/system info
+cd archive/experimental/go/tarsum && go build -o tarsum .
+```
+
+Single-file Go tools (stdlib only, build from anywhere):
+
+```sh
+go build -o csv2json projects/go-tools/csv2json/csv2json.go
+go build -o gosoft   projects/go-tools/gosoft/gosoft.go
+go build -o gouniq   archive/experimental/go/gouniq/gouniq.go
+go build -o gobetween archive/experimental/go/gobetween/gobetween.go
+```
+
+goipgrep (the full project) has its own build tooling:
+
+```sh
+cd projects/go-tools/goipgrep
+make build        # or: ./scripts/build.sh — output lands in dist/ipgrep
+make test
+```
+
+Rust tools (single files, no cargo project needed):
+
+```sh
+rustc -O archive/experimental/rust/uniq.rs    -o uniq
+rustc -O archive/experimental/rust/uniq2.rs   -o uniq2
+rustc -O archive/experimental/rust/between.rs -o between
+```
+
+Build outputs (`dist/`, `bin/`, `*.exe`, `*.test`, and the per-tool binary names
+above) are gitignored — do not commit compiled artifacts.
+
 ## `config/`: Shell, Desktop, and VisiData
 
 - `config/shell/`: shell prompt, aliases, input settings, dircolors, and local completions. `config/shell/completions/eslogger.zsh` is the local Zsh completion for Apple’s `eslogger`.
diff --git a/projects/go-tools/bincmp/gobincmp.go b/projects/go-tools/bincmp/gobincmp.go
index 7364d87..7d49cd1 100644
--- a/projects/go-tools/bincmp/gobincmp.go
+++ b/projects/go-tools/bincmp/gobincmp.go
@@ -26,7 +26,7 @@ Binwally (Go Version): Binary and Directory tree comparison tool
 
 Usage: go run . <dir1/file1> <dir2/file2>
 `
-		fmt.Printf(usage)
+		fmt.Print(usage)
 		os.Exit(1)
 	}
 	path1 := os.Args[1]
@@ -49,7 +49,7 @@ Usage: go run . <dir1/file1> <dir2/file2>
 		compareTrees(path1, path2, &diffs)
 
 		if len(diffs) == 0 {
-			fmt.Println("No diffs found\n")
+			fmt.Println("No diffs found")
 		} else {
 			totalScore := 0
 			for _, score := range diffs {
@@ -61,15 +61,15 @@ Usage: go run . <dir1/file1> <dir2/file2>
 		}
 	} else if !info1.IsDir() && !info2.IsDir() {
 		// Both are files
-		hash1, err := ssdeep.HashFromFile(path1) // CORRECTED
+		hash1, err := ssdeep.FuzzyFilename(path1)
 		if err != nil {
 			log.Fatalf("Failed to hash file %s: %v", path1, err)
 		}
-		hash2, err := ssdeep.HashFromFile(path2) // CORRECTED
+		hash2, err := ssdeep.FuzzyFilename(path2)
 		if err != nil {
 			log.Fatalf("Failed to hash file %s: %v", path2, err)
 		}
-		score, err := ssdeep.Distance(hash1, hash2) // CORRECTED
+		score, err := ssdeep.Distance(hash1, hash2)
 		if err != nil {
 			log.Fatalf("Failed to compare hashes: %v", err)
 		}
@@ -196,9 +196,9 @@ func compareFiles(path1, path2 string, diffs *[]int) {
 
 		if !bytes.Equal(b1, b2) {
 			// Files differ, use ssdeep
-			hash1, _ := ssdeep.HashFromFile(path1)    // CORRECTED
-			hash2, _ := ssdeep.HashFromFile(path2)    // CORRECTED
-			score, _ := ssdeep.Distance(hash1, hash2) // CORRECTED
+			hash1, _ := ssdeep.FuzzyFilename(path1)
+			hash2, _ := ssdeep.FuzzyFilename(path2)
+			score, _ := ssdeep.Distance(hash1, hash2)
 			fmt.Printf("%5s differs %s\n", strconv.Itoa(score), getRelativePath(path1))
 			*diffs = append(*diffs, score)
 			return