add README.md generation in the sketch-dist folder

The generated README.md contains commands that helps on how to replicate the build environment

Author: umbynos

README.md

@@ -1,7 +1,7 @@
 # arduino-cslt
 
 `arduino-cslt` is a convenient wrapper of [arduino-cli](https://github.com/arduino/arduino-cli), it compiles Arduino sketches outputting a precompiled library under `sketch-dist/` folder created in the current working directory.
-It generates a json file in the `extras/` folder that contains information regarding libraries and core to use in order to build the sketch. The result is achieved by parsing the verbose output of `arduino-cli` and by using [GNU ar](https://sourceware.org/binutils/docs/binutils/ar.html) to generate an archive of the object files.
+It generates a README.md file that contains information regarding libraries and core to use in order to build the sketch. The result is achieved by parsing the verbose output of `arduino-cli` and by using [GNU ar](https://sourceware.org/binutils/docs/binutils/ar.html) to generate an archive of the object files.
 
 ## Prequisites
 In order to run this tool you have to install first the [Arduino CLI](https://github.com/arduino/arduino-cli) and have `arduino-cli` binary in your `$PATH`, otherwise `arduino-cslt` won't work.
@@ -15,7 +15,7 @@ In order to build `arduino-cslt` just use `task go:build`
 ## Usage
 `./arduino-cslt compile -b <fqbn> <sketch_path>`
 
-[![asciicast](https://asciinema.org/a/463342.svg)](https://asciinema.org/a/463342)
+[![asciicast](https://asciinema.org/a/465059.svg)](https://asciinema.org/a/465059)
 
 For example, running `./arduino-cslt compile -b arduino:samd:mkrwifi1010 sketch/sketch.ino` should produce a library with the following structure, in the current working directory:
 ```
@@ -28,6 +28,7 @@ sketch-dist/
 │       ├── cortex-m0plus
 │       │   └── libsketch.a
 │       └── libsketch.h
+├── README.md  <--contains information regarding libraries and core to install in order to reproduce the original build environment
 └── sketch
     └── sketch.ino  <-- the actual sketch we are going to compile with the arduino-cli later
 ```
@@ -48,11 +49,26 @@ INFO[0001] restored sketch/sketch.ino
 INFO[0001] created sketch-dist/libsketch/library.properties
 INFO[0001] created sketch-dist/libsketch/src/libsketch.h 
 INFO[0001] created sketch-dist/sketch/sketch.ino 
+INFO[0003] created sketch-dist/README.md 
 INFO[0001] running: gcc-ar rcs sketch-dist/libsketch/src/cortex-m0plus/libsketch.a /tmp/arduino-sketch-E4D76B1781E9EB73A7B3491CAC68F374/sketch/sketch.ino.cpp.o 
 INFO[0001] created sketch-dist/libsketch/src/cortex-m0plus/libsketch.a 
 INFO[0001] created sketch-dist/libsketch/extras/result.json
 ```
 
+The content of `sketch-dist/README.md` included copy-pastable commands to reproduce the build environment:
+```markdown
+This package contains firmware code loaded in your product. 
+The firmware contains additional code licensed with LGPL clause; in order to re-compile the entire firmware bundle, please execute the following.
+
+## Install core and libraries
+`arduino-cli core install arduino:samd@1.8.12`
+`arduino-cli lib install WiFiNINA@1.8.13`
+`arduino-cli lib install SPI@1.0`
+
+## Compile
+`arduino-cli compile -b arduino:samd:mkrwifi1010 sketch-dist/sketch/sketch.ino --library sketch-dist/libsketch`
+```
+
 And the content of `sketch-dist/libsketch/extras/result.json` is:
 ```json
 {
@@ -80,12 +96,12 @@ And the content of `sketch-dist/libsketch/extras/result.json` is:
 ```
 
 ## How to compile the precompiled sketch
-In order to compile the sketch you have first to install manually the libraries and the core listed in the `sketch-dist/<libsketch>/extras/result.json` file.
-
-You can install a library with [`arduino-cli lib install LIBRARY[@VERSION_NUMBER]`](https://arduino.github.io/arduino-cli/latest/commands/arduino-cli_lib_install/).
+In order to compile the sketch you can follow the instructions listed in the `sketch-dist/README.md` file.
 
 You can install a core with [`arduino-cli core install PACKAGER:ARCH[@VERSION]`](https://arduino.github.io/arduino-cli/latest/commands/arduino-cli_core_install/).
 
+You can install a library with [`arduino-cli lib install LIBRARY[@VERSION_NUMBER]`](https://arduino.github.io/arduino-cli/latest/commands/arduino-cli_lib_install/).
+
 After completing that operation you can compile it with:
 
 `arduino-cli compile -b <fqbn> sketch-dist/sketch/sketch.ino --library sketch-dist/<libsketch>`.

cmd/compile.go

@@ -64,10 +64,9 @@ var compileCmd = &cobra.Command{
 	│       ├── cortex-m0plus
 	│       │   └── libsketch.a
 	│       └── libsketch.h
+	├── README.md  <--contains information regarding libraries and core to install in order to reproduce the original build environment
 	└── sketch
-	    └── sketch.ino  <-- the actual sketch we are going to compile with the arduino-cli later
-
-	The result.json file contains information regarding libraries and core to use in order to reproduce the original build environment`,
+	    └── sketch.ino  <-- the actual sketch we can recompile with the arduino-cli later`,
 	Example: os.Args[0] + `compile -b arduino:samd:mkrwifi1010 sketch/sketch.ino`,
 	Args:    cobra.ExactArgs(1), // the path of the sketch to build
 	Run:     compileSketch,
@@ -141,7 +140,7 @@ func compileSketch(cmd *cobra.Command, args []string) {
 
 	sketchName := strings.TrimSuffix(inoPath.Base(), inoPath.Ext())
 	// let's create the library corresponding to the precompiled sketch
-	createLib(sketchName, buildMcu, returnJson, objFilePaths)
+	createLib(sketchName, buildMcu, fqbn, returnJson, objFilePaths)
 }
 
 // parseCliCompileOutput function takes cmdOutToParse as argument,
@@ -274,9 +273,10 @@ func patchSketch(inoPath *paths.Path) (oldSketchContent []byte) {
 // createLib function will take care of creating the library directory structure and files required, for the precompiled library to be recognized as such.
 // sketchName is the name of the sketch without the .ino extension. We use this for the name of the lib.
 // buildMcu is the name of the MCU of the board we have compiled for. The library specifications (https://arduino.github.io/arduino-cli/0.20/library-specification/#precompiled-binaries) requires that the precompiled archive is stored inside a folder with the name of the MCU used during the compile.
+// fqbn is required in order to generate the README.md file with instructions.
 // returnJson is the ResultJson object containing informations regarding core and libraries used during the compile process.
 // objFilePaths is a paths.PathList containing the paths.Paths to all the sketch related object files produced during the compile phase.
-func createLib(sketchName string, buildMcu string, returnJson *ResultJson, objFilePaths *paths.PathList) {
+func createLib(sketchName, buildMcu, fqbn string, returnJson *ResultJson, objFilePaths *paths.PathList) {
 	// we are going to leverage the precompiled library infrastructure to make the linking work.
 	// this type of lib, as the type suggest, is already compiled so it only gets linked during the linking phase of a sketch
 	// but we have to create a library folder structure in the current directory:
@@ -290,6 +290,7 @@ func createLib(sketchName string, buildMcu string, returnJson *ResultJson, objFi
 	// │       ├── cortex-m0plus
 	// │       │   └── libsketch.a
 	// │       └── libsketch.h
+	// ├── README.md  <--contains information regarding libraries and core to install in order to reproduce the original build environment
 	// └── sketch
 	//     └── sketch.ino  <-- the actual sketch we are going to compile with the arduino-cli later
 
@@ -373,6 +374,30 @@ void loop() {
 	sketchFilePath := sketchDir.Join(sketchName + ".ino")
 	createFile(sketchFilePath, sketchFile)
 
+	// generate the commands to run to successfully reproduce the build environment, they will be used as content for the README.md
+	var readmeContent []string
+	readmeContent = append(readmeContent, "`arduino-cli core install "+returnJson.CoreInfo.Id+"@"+returnJson.CoreInfo.Version+"`")
+	for _, readmeLib := range returnJson.LibsInfo {
+		readmeContent = append(readmeContent, "`arduino-cli lib install "+readmeLib.Name+"@"+readmeLib.Version+"`")
+	}
+	// make the paths relative, absolute paths are too long and are different on the user machine
+	sketchFileRelPath, _ := sketchFilePath.RelFrom(workingDir)
+	libRelDir, _ := libDir.RelFrom(workingDir)
+	readmeCompile := "`arduino-cli compile -b " + fqbn + " " + sketchFileRelPath.String() + " --library " + libRelDir.String() + "`"
+
+	//create the README.md file containig instructions regarding what commands to run in order to have again a working binary
+	// the README.md contains the following:
+	readmeMd := `This package contains firmware code loaded in your product. 
+The firmware contains additional code licensed with LGPL clause; in order to re-compile the entire firmware bundle, please execute the following.
+
+## Install core and libraries
+` + strings.Join(readmeContent, "\n") + "\n" + `
+## Compile
+` + readmeCompile + "\n"
+
+	readmeMdPath := rootDir.Join("README.md")
+	createFile(readmeMdPath, readmeMd)
+
 	// run gcc-ar to create an archive containing all the object files except the main.cpp.o (we don't need it because we have created a substitute of it before ⬆️)
 	// we exclude the main.cpp.o because we are going to link the archive libsketch.a against sketchName.ino
 	objFilePaths.FilterOutPrefix("main.cpp")