documentation

cmd/yap/command/root.go

@@ -15,8 +15,9 @@ Complete documentation is available at
 🌐 https://github.com/M0Rf30/yap`,
 }
 
-// Execute adds all child commands to the root command and sets flags appropriately.
-// This is called by main.main(). It only needs to happen once to the rootCmd.
+// Execute adds all child commands to the root command and sets flags
+// appropriately. This is called by main.main(). It only needs to happen once to
+// the rootCmd.
 func Execute() {
 	cobra.CheckErr(rootCmd.Execute())
 }

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,9 @@
 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,28 @@ 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,12 @@ 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 +65,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, it binds any element (variable,
+// array, function) 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 +92,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 +135,9 @@ 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 +154,9 @@ 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 +175,8 @@ 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 +197,8 @@ 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 +228,8 @@ 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 +249,8 @@ 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 +295,10 @@ 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 +353,8 @@ 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,8 @@ 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 {

pkg/utils/strings.go

@@ -11,10 +11,9 @@ import (
 	"mvdan.cc/sh/v3/syntax"
 )
 
-// GenerateRandomString returns a securely generated random string.
-// It will return an error if the system's secure random
-// number generator fails to function correctly, in which
-// case the caller should not continue.
+// GenerateRandomString returns a securely generated random string. It will
+// return an error if the system's secure random number generator fails to
+// function correctly, in which case the caller should not continue.
 func GenerateRandomString(n int) string {
 	const letters = "0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz-"
 
@@ -32,7 +31,8 @@ func GenerateRandomString(n int) string {
 	return string(ret)
 }
 
-// Generates a string from a *syntax.Assign of an array declaration.
+// StringifyArray generates a string from a *syntax.Assign of an array
+// declaration.
 func StringifyArray(node *syntax.Assign) []string {
 	fields := make([]string, 0)
 	printer := syntax.NewPrinter(syntax.Indent(2))
@@ -55,7 +55,8 @@ func StringifyArray(node *syntax.Assign) []string {
 	return fields
 }
 
-// Generates a string from a *syntax.Assign of a variable declaration.
+// StringifyAssign generates a string from a *syntax.Assign of a variable
+// declaration.
 func StringifyAssign(node *syntax.Assign) string {
 	out := &strings.Builder{}
 	printer := syntax.NewPrinter(syntax.Indent(2))
@@ -72,7 +73,8 @@ func StringifyAssign(node *syntax.Assign) string {
 	return strings.Trim(out.String(), "\"")
 }
 
-// Generates strings from a *syntax.Assign of a function declaration.
+// StringifyFuncDecl generates strings from a *syntax.Assign of a function
+// declaration.
 func StringifyFuncDecl(node *syntax.FuncDecl) string {
 	out := &strings.Builder{}
 	printer := syntax.NewPrinter(syntax.Indent(2))