documentation

pkg/builder/builder.go

@@ -9,10 +9,13 @@ import (
 	"github.com/M0Rf30/yap/pkg/utils"
 )
 
+// Builder maps PKGBUILD to generic functions aimed at artifacts generation.
 type Builder struct {
 	PKGBUILD *pkgbuild.PKGBUILD
 }
 
+// Compile manages all the instructions that lead to a single project artifact.
+// It returns any error if occurred.
 func (builder *Builder) Compile() error {
 	err := builder.initDirs()
 	if err != nil {
@@ -52,6 +55,8 @@ func (builder *Builder) Compile() error {
 	return err
 }
 
+// Package executes the instructions provided by a single project package() function.
+// It returns any error if occurred.
 func (builder *Builder) Package() error {
 	err := RunScript(builder.PKGBUILD.Package)
 	if err != nil {
@@ -61,6 +66,8 @@ func (builder *Builder) Package() error {
 	return err
 }
 
+// build executes the instructions provided by a single project build() function.
+// It returns any error if occurred.
 func (builder *Builder) build() error {
 	err := RunScript(builder.PKGBUILD.Build)
 	if err != nil {
@@ -70,6 +77,8 @@ func (builder *Builder) build() error {
 	return err
 }
 
+// getSources detects sources provided by a single project source array and downloads them if occurred.
+// It returns any error if occurred.
 func (builder *Builder) getSources() error {
 	var err error
 
@@ -92,6 +101,8 @@ func (builder *Builder) getSources() error {
 	return err
 }
 
+// initDirs creates mandatory fakeroot folders (src, pkg) for a single project.
+// It returns any error if occurred.
 func (builder *Builder) initDirs() error {
 	err := utils.ExistsMakeDir(builder.PKGBUILD.SourceDir)
 	if err != nil {

pkg/options/strip.go

@@ -1,5 +1,8 @@
 package options
 
+// StripScript is a scriptlet taken from makepkg resources.
+// It's executed by mvdan/sh interpreter and provides strip instructions to dpkg-buildpackage.
+// Although it's a very dirty solution, for now it's the faster way to have this essential feature.
 const StripScript = `
 strip_file() {
 	local binary=$1; shift

pkg/packer/packer.go

@@ -12,14 +12,27 @@ import (
 	"github.com/M0Rf30/yap/pkg/redhat"
 )
 
+// Packer is the common interface implemented by all package managers.
 type Packer interface {
+	// Prepare appends the dependencies required to build all the projects.
+	// It returns any error if encountered.
 	Prepare(depends []string) error
+	// Build reads the path where the final artifact will be written.
+	// It returns any error if encountered.
 	Build(output string) error
+	// Install reads the path where the final artifact will be written.
+	// It returns any error if encountered.
 	Install(output string) error
+	// PrepareEnvironment reads a flag to install golang tools on request, on the build machine.
+	// It returns any error if encountered.
 	PrepareEnvironment(flag bool) error
+	// Update performs a package manager update operation.
+	// It returns any error if encountered.
 	Update() error
 }
 
+// GetPackageManager reads the pkgBuild structure and the distro name.
+// It returns a Packer interface representing the specialized package manager for that distro.
 func GetPackageManager(pkgBuild *pkgbuild.PKGBUILD, distro string) Packer {
 	var packageManager Packer
 

pkg/pkgbuild/pkgbuild.go

@@ -14,8 +14,11 @@ import (
 	"mvdan.cc/sh/v3/shell"
 )
 
+// Verbos is a flag to enable verbose output
 var Verbose bool
 
+// PKGBUILD defines all the fields accepted by the yap specfile (variables, arrays, functions).
+// It adds some exotics fields to manage debconfig templating and other rpm/deb descriptors.
 type PKGBUILD struct {
 	Arch           []string
 	Backup         []string
@@ -61,6 +64,10 @@ type PKGBUILD struct {
 	priorities     map[string]int
 }
 
+// AddItem reads a key and the related data.
+// It checks the key for __ token and give to it a priority value.
+// After that binds every element (variable, array, funtion) to the current environment.
+// It returns any error if encountered.
 func (pkgBuild *PKGBUILD) AddItem(key string, data any) error {
 	key, priority, err := pkgBuild.parseDirective(key)
 	if err != nil {
@@ -84,6 +91,9 @@ func (pkgBuild *PKGBUILD) AddItem(key string, data any) error {
 	return err
 }
 
+// CreateSpec reads the filepath where the specfile will be written and the content of the specfile.
+// Specfile generation is done using go templates for every different distro family.
+// It returns any error if encountered.
 func (pkgBuild *PKGBUILD) CreateSpec(filePath, script string) error {
 	cleanFilePath := filepath.Clean(filePath)
 
@@ -124,6 +134,8 @@ func (pkgBuild *PKGBUILD) CreateSpec(filePath, script string) error {
 	return err
 }
 
+// GetDepends reads the package manager name, its arguments and all the dependencies required to build the package.
+// It returns any error if encountered.
 func (pkgBuild *PKGBUILD) GetDepends(packageManager string, args, makeDepends []string) error {
 	var err error
 	if len(makeDepends) == 0 {
@@ -140,6 +152,8 @@ func (pkgBuild *PKGBUILD) GetDepends(packageManager string, args, makeDepends []
 	return err
 }
 
+// GetUpdates reads the package manager name and its arguments to perform a sync with remotes and consequently retrieve updates.
+// It returns any error if encountered.
 func (pkgBuild *PKGBUILD) GetUpdates(packageManager string, args ...string) error {
 	err := utils.Exec("", packageManager, args...)
 	if err != nil {
@@ -158,6 +172,7 @@ func (pkgBuild *PKGBUILD) Init() {
 	}
 }
 
+// Validate checks that mandatory items are correctly provided by the PKGBUILD file.
 func (pkgBuild *PKGBUILD) Validate() {
 	if len(pkgBuild.SourceURI) != len(pkgBuild.HashSums) {
 		fmt.Printf("%s%s ❌ :: %snumber of sources and hashsums differs%s\n",
@@ -178,6 +193,7 @@ func (pkgBuild *PKGBUILD) Validate() {
 	}
 }
 
+// mapArrays reads an array name and its content and maps them to the PKGBUILD struct.
 func (pkgBuild *PKGBUILD) mapArrays(key string, data any) {
 	switch key {
 	case "arch":
@@ -207,6 +223,7 @@ func (pkgBuild *PKGBUILD) mapArrays(key string, data any) {
 	}
 }
 
+// mapFunctions reads a function name and its content and maps them to the PKGBUILD struct.
 func (pkgBuild *PKGBUILD) mapFunctions(key string, data any) {
 	switch key {
 	case "build":
@@ -226,6 +243,7 @@ func (pkgBuild *PKGBUILD) mapFunctions(key string, data any) {
 	}
 }
 
+// mapVariables reads a variable name and its content and maps them to the PKGBUILD struct.
 func (pkgBuild *PKGBUILD) mapVariables(key string, data any) {
 	var err error
 
@@ -270,6 +288,9 @@ func (pkgBuild *PKGBUILD) mapVariables(key string, data any) {
 	}
 }
 
+// parseDirective reads a directive string and detect any specialized one (i.e only to be applied for ubuntu).
+// It detects if distro codename is given and calculates and assigns a priority to the directive.
+// It returns the directive key, assigned priority and any error if occurred.
 func (pkgBuild *PKGBUILD) parseDirective(input string) (string, int, error) {
 	split := strings.Split(input, "__")
 	key := split[0]
@@ -324,6 +345,7 @@ func (pkgBuild *PKGBUILD) parseDirective(input string) (string, int, error) {
 	return key, priority, err
 }
 
+// setMainFolders checks for pkgbuild distro values and initialize the build fakeroot accordingly.
 func (pkgBuild *PKGBUILD) setMainFolders() {
 	if pkgBuild.Distro == "arch" {
 		pkgBuild.PackageDir = filepath.Join(pkgBuild.StartDir, "pkg", pkgBuild.PkgName)

pkg/project/project.go

@@ -28,6 +28,7 @@ type DistroProject interface {
 	Prepare() error
 }
 
+// MultipleProject defnes the content of yap.json specfile and some in-memory objects.
 type MultipleProject struct {
 	makeDepends    []string
 	packageManager packer.Packer

pkg/source/source.go

@@ -192,6 +192,8 @@ func (src *Source) symlinkSources() error {
 	return err
 }
 
+// validate checks that items declared in the source array
+// have a valid hashsum. It returns any error encountered.
 func (src *Source) validate() error {
 	info, err := os.Stat(filepath.Join(src.StartDir, src.SourceItemPath))
 	if err != nil {