deb-mock/docs/FAQ.md

Deb-Mock FAQ

Frequently Asked Questions

This FAQ addresses common issues and questions about Deb-Mock, a Debian-focused alternative to Fedora's Mock.

Environment Variables in Chroot

Q: I set environment variables in my configuration, but they're not preserved in the chroot environment.

A: This is a common issue with chroot environments. Deb-Mock provides several solutions:

Solution 1: Use the --preserve-env flag

deb-mock shell --preserve-env

Solution 2: Configure specific environment variables

# deb-mock.yaml
preserve_environment:
  - CC
  - CXX
  - CFLAGS
  - CXXFLAGS
  - DEB_BUILD_OPTIONS
  - CCACHE_DIR

Solution 3: Disable environment sanitization

# deb-mock.yaml
environment_sanitization: false

Solution 4: Use the --env-var option

deb-mock shell --env-var CC=gcc --env-var CFLAGS="-O2"

Why this happens: Chroot environments sanitize environment variables for security reasons. Deb-Mock provides controlled ways to preserve necessary variables while maintaining security.

Cross-Distribution Package Building

Q: I'm on Debian Stable but need to build packages for Debian Sid. How can I do this?

A: Use Deb-Mock's bootstrap chroot feature, similar to Mock's --bootstrap-chroot:

Solution: Use bootstrap chroot

# Create a Sid chroot using bootstrap
deb-mock init-chroot debian-sid-amd64 --suite sid --bootstrap

# Build packages in the Sid chroot
deb-mock -r debian-sid-amd64 build package.dsc

Configuration-based approach

# deb-mock.yaml
use_bootstrap_chroot: true
bootstrap_chroot_name: "debian-stable-bootstrap"
suite: "sid"
architecture: "amd64"

Why this is needed: Building packages for newer distributions on older systems can fail due to package manager version incompatibilities. Bootstrap chroots create a minimal environment with the target distribution's tools to build the final chroot.

Build Dependencies Not Found

Q: My build fails with "Package not found" errors for build dependencies.

A: This usually indicates repository or dependency resolution issues:

Solution 1: Update the chroot

deb-mock update-chroot debian-bookworm-amd64

Solution 2: Check repository configuration

# deb-mock.yaml
mirror: "http://deb.debian.org/debian/"
security_mirror: "http://security.debian.org/debian-security/"
backports_mirror: "http://deb.debian.org/debian/"

Solution 3: Install missing dependencies manually

deb-mock shell debian-bookworm-amd64
# Inside chroot:
apt-get update
apt-get install build-essential devscripts

Solution 4: Use verbose output for debugging

deb-mock --verbose build package.dsc

Chroot Creation Fails

Q: I get permission errors when creating chroots.

A: Chroot creation requires root privileges:

Solution 1: Use sudo

sudo deb-mock init-chroot debian-bookworm-amd64

Solution 2: Add user to appropriate groups

sudo usermod -a -G sbuild $USER
# Log out and back in

Solution 3: Check disk space

df -h /var/lib/deb-mock

Solution 4: Verify debootstrap installation

sudo apt-get install debootstrap schroot

Build Performance Issues

Q: My builds are slow. How can I speed them up?

A: Deb-Mock provides several performance optimization features:

Solution 1: Enable caching

# deb-mock.yaml
use_root_cache: true
use_package_cache: true
use_ccache: true

Solution 2: Use parallel builds

# deb-mock.yaml
parallel_jobs: 8
parallel_compression: true

Solution 3: Use tmpfs for temporary files

# deb-mock.yaml
use_tmpfs: true
tmpfs_size: "4G"

Solution 4: Clean up old caches

deb-mock cleanup-caches

Network and Proxy Issues

Q: I'm behind a proxy and can't download packages.

A: Configure proxy settings in your configuration:

Solution: Configure proxy

# deb-mock.yaml
http_proxy: "http://proxy.example.com:3128"
https_proxy: "http://proxy.example.com:3128"
no_proxy: "localhost,127.0.0.1"

Package Signing Issues

Q: How do I sign packages with GPG keys?

A: Deb-Mock supports package signing through configuration:

Solution: Configure signing

# deb-mock.yaml
sign_packages: true
gpg_key: "your-gpg-key-id"
gpg_passphrase: "your-passphrase"  # Use environment variable in production

Debugging Build Failures

Q: My build failed. How can I debug it?

A: Deb-Mock provides several debugging tools:

Solution 1: Use verbose output

deb-mock --verbose build package.dsc

Solution 2: Keep chroot for inspection

deb-mock build package.dsc --keep-chroot
deb-mock shell  # Inspect the failed build environment

Solution 3: Check build logs

# Build logs are automatically captured
ls -la ./output/
cat ./output/build.log

Solution 4: Use debug mode

deb-mock --debug build package.dsc

Chain Building Issues

Q: My chain build fails because later packages can't find earlier packages.

A: This is a common issue with chain builds:

Solution 1: Use the chain command

deb-mock chain package1.dsc package2.dsc package3.dsc

Solution 2: Continue on failure

deb-mock chain package1.dsc package2.dsc --continue-on-failure

Solution 3: Check package installation

deb-mock shell
# Inside chroot, check if packages are installed:
dpkg -l | grep package-name

Configuration Issues

Q: How do I create a custom configuration?

A: Deb-Mock supports custom configurations:

Solution 1: Create a custom config file

# my-config.yaml
chroot_name: "custom-debian"
architecture: "amd64"
suite: "bookworm"
mirror: "http://deb.debian.org/debian/"
use_root_cache: true
use_ccache: true
parallel_jobs: 4

Solution 2: Use the config file

deb-mock -c my-config.yaml build package.dsc

Solution 3: Use core configurations

# List available configurations
deb-mock list-configs

# Use a core configuration
deb-mock -r debian-bookworm-amd64 build package.dsc

Common Error Messages

"Chroot does not exist"

# Create the chroot first
deb-mock init-chroot debian-bookworm-amd64

"Permission denied"

# Use sudo for chroot operations
sudo deb-mock init-chroot debian-bookworm-amd64

"Package not found"

# Update the chroot
deb-mock update-chroot debian-bookworm-amd64

"Build dependencies not satisfied"

# Install build dependencies
deb-mock shell
# Inside chroot:
apt-get install build-essential devscripts

Getting Help

Q: Where can I get more help?

A: Several resources are available:

1. Documentation: Check the main README and configuration documentation
2. Verbose Output: Use --verbose and --debug flags for detailed information
3. Error Messages: Deb-Mock provides detailed error messages with suggestions
4. Logs: Check build logs in the output directory
5. Community: Report issues on the project's issue tracker

Performance Tips

1. Use caching: Enable root cache, package cache, and ccache
2. Parallel builds: Set appropriate parallel_jobs for your system
3. Clean up: Regularly run deb-mock cleanup-caches
4. Monitor resources: Use deb-mock cache-stats to monitor cache usage
5. Optimize chroots: Use tmpfs for temporary files if you have sufficient RAM

Security Considerations

1. Environment sanitization: Keep environment sanitization enabled unless necessary
2. Root privileges: Only use sudo when required for chroot operations
3. Package verification: Verify source packages before building
4. Network security: Use HTTPS mirrors and configure proxies securely
5. Cache security: Regularly clean caches to remove sensitive build artifacts