GemReader/docs/building.md

Building GemReader

This document provides detailed instructions on how to build the GemReader application for different platforms, with a focus on creating executable files (especially .exe files for Windows).

Prerequisites

Before building GemReader, ensure you have the following installed:

• Go 1.24 or higher
• Git (for cloning the repository)
• A terminal/command prompt
• For Windows: A modern version of Windows that supports Go compilation

Building for Windows (.exe)

Basic Build

To build the application for Windows and create an .exe file, run the following command:

go build -o gemreader.exe cmd/gemreader/main.go

This will create a gemreader.exe file in your current directory.

Cross-compilation from Other Platforms

If you're building from a non-Windows platform (Linux or macOS) and want to create a Windows executable, use these commands:

GOOS=windows GOARCH=amd64 go build -o gemreader.exe cmd/gemreader/main.go

Advanced Build Options

Building with release flags (optimized)

For a more optimized build with smaller file size:

go build -ldflags "-s -w" -o gemreader.exe cmd/gemreader/main.go

• -s: Omit the symbol table and debug information
• -w: Omit the DWARF symbol table

Building with version information

To embed version information in the executable:

go build -ldflags "-X main.Version=1.0.0 -s -w" -o gemreader.exe cmd/gemreader/main.go

Building for Other Platforms

This section covers building the application on Windows for other operating systems using Go's cross-compilation feature.

From Windows to Linux

To build for Linux from a Windows machine, you have several options:

Option 1: Using PowerShell (Recommended)

# For 64-bit Linux
$env:GOOS="linux"; $env:GOARCH="amd64"; go build -o gemreader-linux cmd/gemreader/main.go

# For 32-bit Linux  
$env:GOOS="linux"; $env:GOARCH="386"; go build -o gemreader-linux-386 cmd/gemreader/main.go

# For ARM64 Linux
$env:GOOS="linux"; $env:GOARCH="arm64"; go build -o gemreader-linux-arm64 cmd/gemreader/main.go

Option 2: Using Command Prompt (CMD) In Command Prompt, you need to set the environment variables persistently for the session:

go env -w GOOS=linux
go env -w GOARCH=amd64
go build -o gemreader-linux cmd/gemreader/main.go

# Reset to default after building
go env -w GOOS=windows
go env -w GOARCH=amd64

Option 3: Temporary environment variables in PowerShell (One-liner)

$env:GOOS="linux"; $env:GOARCH="amd64"; go build -o gemreader-linux cmd/gemreader/main.go; $env:GOOS="windows"; $env:GOARCH="amd64"

From Windows to macOS

To build for macOS from a Windows machine:

Using PowerShell:

# For Intel-based Macs
$env:GOOS="darwin"; $env:GOARCH="amd64"; go build -o gemreader-mac cmd/gemreader/main.go

# For Apple Silicon Macs (M1/M2/M3)
$env:GOOS="darwin"; $env:GOARCH="arm64"; go build -o gemreader-mac-arm64 cmd/gemreader/main.go

Using Command Prompt:

go env -w GOOS=darwin
go env -w GOARCH=amd64
go build -o gemreader-mac cmd/gemreader/main.go

# Reset to default after building
go env -w GOOS=windows
go env -w GOARCH=amd64

Using PowerShell

If you're using PowerShell instead of Command Prompt, the syntax is slightly different:

# For Linux ARM64
$env:GOOS="linux"; $env:GOARCH="arm64"; go build -o gemreader-linux-arm64 cmd/gemreader/main.go

# For macOS
$env:GOOS="darwin"; $env:GOARCH="arm64"; go build -o gemreader-mac-arm64 cmd/gemreader/main.go

Common GOOS and GOARCH Values

GOOS	GOARCH	Platform
windows	amd64	64-bit Windows
windows	386	32-bit Windows
windows	arm64	64-bit Windows on ARM
linux	amd64	64-bit Linux
linux	386	32-bit Linux
linux	arm64	64-bit Linux on ARM
darwin	amd64	64-bit macOS (Intel)
darwin	arm64	64-bit macOS (Apple Silicon)

Building for Multiple Platforms

You can create a batch script to build for multiple platforms at once. Here's an example build-all.bat:

@echo off
echo Building GemReader for multiple platforms...

REM Create dist directory if it doesn't exist
if not exist dist mkdir dist

echo Building for Windows (64-bit)...
go env -w GOOS=windows
go env -w GOARCH=amd64
go build -ldflags "-s -w" -o dist/gemreader-windows-amd64.exe cmd/gemreader/main.go

echo Building for Linux (64-bit)...
go env -w GOOS=linux
go env -w GOARCH=amd64
go build -ldflags "-s -w" -o dist/gemreader-linux-amd64 cmd/gemreader/main.go

echo Building for macOS (Intel)...
go env -w GOOS=darwin
go env -w GOARCH=amd64
go build -ldflags "-s -w" -o dist/gemreader-darwin-amd64 cmd/gemreader/main.go

echo Building for macOS (Apple Silicon)...
go env -w GOOS=darwin
go env -w GOARCH=arm64
go build -ldflags "-s -w" -o dist/gemreader-darwin-arm64 cmd/gemreader/main.go

echo Resetting GOOS and GOARCH to default...
go env -w GOOS=windows
go env -w GOARCH=amd64

echo Build process completed!
pause

Alternatively, you can create a PowerShell script build-all.ps1 for more reliable cross-platform building:

Write-Host "Building GemReader for multiple platforms..."

# Create dist directory if it doesn't exist
if (!(Test-Path dist)) {
    New-Item -ItemType Directory -Path dist
}

# Build for Windows
Write-Host "Building for Windows (64-bit)..."
$env:GOOS="windows"
$env:GOARCH="amd64"
go build -ldflags "-s -w" -o dist/gemreader-windows-amd64.exe cmd/gemreader/main.go

# Build for Linux
Write-Host "Building for Linux (64-bit)..."
$env:GOOS="linux"
$env:GOARCH="amd64"
go build -ldflags "-s -w" -o dist/gemreader-linux-amd64 cmd/gemreader/main.go

# Build for macOS Intel
Write-Host "Building for macOS (Intel)..."
$env:GOOS="darwin"
$env:GOARCH="amd64"
go build -ldflags "-s -w" -o dist/gemreader-darwin-amd64 cmd/gemreader/main.go

# Build for macOS Apple Silicon
Write-Host "Building for macOS (Apple Silicon)..."
$env:GOOS="darwin"
$env:GOARCH="arm64"
go build -ldflags "-s -w" -o dist/gemreader-darwin-arm64 cmd/gemreader/main.go

Write-Host "Build process completed!"

Using Build Scripts

For more complex builds, you can create a build script. Here's an example build.bat for Windows:

@echo off
echo Building GemReader for Windows...

REM Build the application
go build -ldflags "-s -w" -o gemreader.exe cmd/gemreader/main.go

if %ERRORLEVEL% == 0 (
    echo Build successful! gemreader.exe has been created.
) else (
    echo Build failed!
    exit /b %ERRORLEVEL%
)

And a build.sh script for Unix-like systems:

#!/bin/bash
echo "Building GemReader..."

# Build the application
go build -ldflags "-s -w" -o gemreader cmd/gemreader/main.go

if [ $? -eq 0 ]; then
    echo "Build successful! gemreader has been created."
else
    echo "Build failed!"
    exit 1
fi

Build Targets with Go Releaser (Alternative Approach)

If the project uses GoReleaser or similar tools, you can use:

# Install GoReleaser if not already installed
go install github.com/goreleaser/goreleaser@latest

# Build all targets defined in .goreleaser.yml
goreleaser build --single-target --snapshot

Troubleshooting Build Issues

Common Issues

Missing Dependencies

If you encounter dependency issues, run:

go mod tidy

This will ensure all dependencies are downloaded and the go.mod file is updated.

CGO Issues

If your build fails due to CGO issues (uncommon for this project), you can disable CGO:

CGO_ENABLED=0 go build -o gemreader.exe cmd/gemreader/main.go

Large Executable Size

If the resulting executable is too large, consider these options:

1. Use the -ldflags "-s -w" options as mentioned above

2. Use UPX to compress the executable (third-party tool):

   upx --best gemreader.exe
   

Checking Build Information

To verify your build information, you can use:

go version -m gemreader.exe

This will show build information about the executable.

Production Builds

For production releases, consider using these flags to create a minimal executable:

go build \
  -ldflags="-s -w -X main.Version=1.0.0" \
  -o gemreader.exe \
  cmd/gemreader/main.go

Verifying the Build

After building, you can test your executable by running:

# On Windows
.\gemreader.exe sample.md

# Or with a different markdown file
.\gemreader.exe path\to\your\markdown\file.md

Build Artifacts

The build process will create:

• gemreader.exe (or platform-specific executable)
• The executable is self-contained and doesn't require additional files to run
• Configuration files like config.toml and sample.md can be distributed separately if needed

Creating an Installer (Optional)

For distribution purposes, you may want to create an installer for Windows using tools like:

• NSIS (Nullsoft Scriptable Install System)
• Inno Setup
• GoReleaser with nfpm for cross-platform packaging

This is outside the scope of this document but worth considering for production releases.