This document provides detailed information about the Gradle build system for the Bearsampp Python module.

The build system is implemented using pure Gradle (no wrapper) and provides:

• Pure Gradle Build: No Ant dependencies, fully native Gradle implementation
• Python-Specific Features: PIP upgrades, wheel package management
• Multiple Version Support: Build any Python version in the bin/ directory
• Incremental Builds: Gradle caching for faster builds
• Parallel Execution: Multi-threaded build execution
• Interactive & Non-Interactive Modes: Flexible build workflows

The main build.gradle file is organized into several sections:

1. Plugin Configuration: Base plugin for fundamental build capabilities
2. Property Loading: Loads configuration from build.properties
3. Project Configuration: Sets up project metadata and paths
4. Task Definitions: Defines all build, verification, and help tasks
5. Lifecycle Hooks: Configures build lifecycle events

The build system uses multiple property sources:

• build.properties: Bundle configuration (name, version, type, format)
• gradle.properties: Gradle daemon and JVM settings
• releases.properties: Available Python release versions
• wheel.properties: Wheel package URLs (per Python version)

ext {
    projectBasedir = projectDir.absolutePath
    rootDir = projectDir.parent
    devPath = file("${rootDir}/dev").absolutePath
    buildPath = "${System.getProperty('user.home')}/Bearsampp-build"
    tmpPath = "${buildPath}/tmp"
    releasePath = "${buildPath}/release"
}

Main task for building release packages.

Usage:

# Interactive mode (lists available versions)
gradle release

# Non-interactive mode (specify version)
gradle release "-PbundleVersion=3.13.5"

Process:

1. Validates Python version exists
2. Creates temporary build directory
3. Copies bundle files (excludes pyqt5)
4. Upgrades PIP to latest version
5. Downloads wheel packages
6. Installs wheel packages
7. Creates 7z archive
8. Cleans up temporary files

Properties:

• bundleVersion: Python version to build (e.g., "3.13.5")

Removes build artifacts and temporary files.

Usage:

gradle clean

Cleans:

• build/ directory
• Temporary build directories in configured build path

Comprehensive environment verification.

Usage:

gradle verify

Checks:

• Java version (8+)
• Required files (build.gradle, build.properties, releases.properties)
• Dev directory structure
• Python versions in bin/
• 7-Zip availability

Validates build.properties configuration.

Usage:

gradle validateProperties

Validates:

• bundle.name
• bundle.release
• bundle.type
• bundle.format

Validates Python version directory structure.

Usage:

gradle validatePythonVersion "-PbundleVersion=3.13.5"

Checks:

• Version directory exists
• bin/ subdirectory
• wheel/ subdirectory
• bearsampp.conf file
• bin/python.bat file
• wheel.properties file
• install.bat file
• Wheel URL configuration

Displays comprehensive build information.

Usage:

gradle info

Shows:

• Project metadata
• Bundle properties
• Path configuration
• Java version
• Gradle version
• Available features
• Quick start commands

Lists available Python versions in bin/ directory.

Usage:

gradle listVersions

Output:

• All Python versions found
• Wheel package information (if available)
• Example build command

Lists all releases from releases.properties.

Usage:

gradle listReleases

Output:

• Version numbers
• Download URLs
• Total count

Displays wheel package information for a specific version.

Usage:

gradle showWheelInfo "-PbundleVersion=3.13.5"

Shows:

• Wheel URL
• Wheel filename
• Wheel directory location
• Install script content

Configure Gradle behavior in gradle.properties:

# Enable Gradle daemon for faster builds
org.gradle.daemon=true

# Enable parallel execution
org.gradle.parallel=true

# Enable build caching
org.gradle.caching=true

# JVM settings
org.gradle.jvmargs=-Xmx2g -XX:MaxMetaspaceSize=512m -XX:+HeapDumpOnOutOfMemoryError

# Console output
org.gradle.console=auto
org.gradle.warning.mode=all

Configure bundle in build.properties:

# Bundle identification
bundle.name = python
bundle.release = 2025.8.21
bundle.type = tools
bundle.format = 7z

# Optional: Custom build path
#build.path = C:/Bearsampp-build

Configure Gradle features in settings.gradle:

rootProject.name = 'module-python'

// Enable stable configuration cache
enableFeaturePreview('STABLE_CONFIGURATION_CACHE')

// Configure build cache
buildCache {
    local {
        enabled = true
        directory = file("${rootDir}/.gradle/build-cache")
    }
}

Each Python version in bin/ must follow this structure:

bin/python{version}/
├── bin/
│   ├── python.bat          # Python launcher script
│   └── python.exe          # Python executable
├── wheel/
│   ├── wheel.properties    # Wheel package URL
│   └── install.bat         # Wheel installation script
├── bearsampp.conf          # Bearsampp configuration
└── [other Python files]

wheel=https://example.com/path/to/package.whl

@echo off
python.bat -m pip install wheel-package.whl

When running gradle release:

1. Initialization Phase

   • Load settings.gradle
   • Configure build cache
   • Initialize project

2. Configuration Phase

   • Load build.gradle
   • Load properties files
   • Configure tasks
   • Validate environment

3. Execution Phase

   • Execute release task
   • Run Python-specific steps
   • Create archive
   • Clean up

gradle.taskGraph.whenReady { graph ->
    // Executed when task graph is ready
    println "Starting Bearsampp Module Python Build"
}

Gradle caching is enabled by default:

• Local Cache: .gradle/build-cache/
• Configuration Cache: Speeds up configuration phase
• Task Output Caching: Reuses task outputs when inputs haven't changed

Multiple tasks can run in parallel when enabled:

org.gradle.parallel=true

Gradle tracks task inputs and outputs:

• Only runs tasks when inputs change
• Skips up-to-date tasks
• Provides "FROM-CACHE" indicators

Override the default build path:

# In build.properties
build.path = D:/CustomBuildPath

Change the archive format:

# In build.properties
bundle.format = zip

Supported formats: 7z, zip, tar, tar.gz

Add custom tasks to build.gradle:

tasks.register('myCustomTask') {
    group = 'custom'
    description = 'My custom task'
    
    doLast {
        println "Executing custom task"
    }
}

Adjust JVM settings for better performance:

# Increase heap size for large builds
org.gradle.jvmargs=-Xmx4g -XX:MaxMetaspaceSize=1g

# Enable G1GC for better garbage collection
org.gradle.jvmargs=-Xmx2g -XX:+UseG1GC

The Gradle daemon improves build performance:

# Enable daemon (default)
org.gradle.daemon=true

# Daemon idle timeout (milliseconds)
org.gradle.daemon.idletimeout=3600000

Optimize cache settings:

buildCache {
    local {
        enabled = true
        directory = file("${rootDir}/.gradle/build-cache")
        removeUnusedEntriesAfterDays = 30
    }
}

Cause: Missing dev project in parent directory

Solution: Ensure dev project exists:

Bearsampp-development/
├── module-python/
└── dev/

Cause: 7z command not in PATH

Solution: Install 7-Zip and add to PATH

Cause: Python version doesn't exist in bin/

Solution: Verify version directory exists:

gradle listVersions

Cause: Gradle daemon issues

Solution: Stop daemon and retry:

gradle --stop
gradle release "-PbundleVersion=3.13.5"

Run with debug output:

gradle release "-PbundleVersion=3.13.5" --debug

Show full stack traces:

gradle release "-PbundleVersion=3.13.5" --stacktrace

1. Always verify environment first: Run gradle verify before building
2. Use specific versions: Specify -PbundleVersion for reproducible builds
3. Clean between major changes: Run gradle clean when switching versions
4. Monitor build cache: Periodically clean old cache entries
5. Keep Gradle updated: Use latest stable Gradle version
6. Document custom changes: Add comments for any build script modifications

• Gradle Documentation
• Gradle Build Cache
• Gradle Performance
• Bearsampp Project