Troubleshooting

Overview

This guide covers common problems encountered during the Miele-LXIV Easy build process and provides practical solutions. Build logs are stored in log/ directory for detailed diagnostics.

Build Log Usage

Always capture build output for troubleshooting:

mkdir -p log
script log/$(date +%Y%m%d_%H%M).txt
./build.sh ; exit

Logs help identify:

Missing dependencies
Configuration errors
Compilation failures
Linking problems

Common Issues

kconfig-mconf not found

Error message:

Please install kconfig-mconf

Cause: The kconfig-mconf tool is not installed or not in PATH.Solution:Install kconfig-mconf following the NuttX project method:

# Install dependencies
brew install gperf ncurses flex bison

# Download and build kconfig-frontends
mkdir -p ~/src/nuttx/tools
cd ~/src/nuttx/tools
git clone https://bitbucket.org/nuttx/tools.git
cd tools/kconfig-frontends

# Configure and install
./configure --disable-shared --enable-static \
            --disable-gconf --disable-qconf \
            --disable-nconf --disable-utils
make
sudo make install

# Verify installation
which kconfig-mconf

Verification:

kconfig-mconf --version

cmake command not found

Error message:

Please install the command-line cmake

Cause: The cmake CLI tool is not installed or not in PATH.Solution 1 - Install via Homebrew:

brew install cmake
which cmake  # Should show /usr/local/bin/cmake or /opt/homebrew/bin/cmake

Solution 2 - Install from CMake.app:

sudo "/Applications/CMake.app/Contents/bin/cmake-gui" --install

This creates symlinks in /usr/local/bin/:

cmake
ctest
cpack
cmake-gui

Verification:

cmake --version

Download fails with curl/wget errors

Error message:

curl: (6) Could not resolve host: dicom.offis.de
wget: unable to resolve host address

Cause: Network connectivity issues or missing download tools.Solution 1 - Check network:

ping dicom.offis.de
ping github.com

Solution 2 - Install wget:

brew install wget

Solution 3 - Manual download: If automated download fails, download manually:

cd $SRC
# Visit https://dicom.offis.de/dcmtk in browser
# Download dcmtk-3.6.5.tar.gz manually
tar -zxf dcmtk-3.6.5.tar.gz

Solution 4 - Use alternate sources: Some libraries have GitHub mirrors. Edit build.sh to use alternate URLs.

Patch fails to apply

Error message:

patching file dcmdata/libsrc/dcdatset.cc
Hunk #1 FAILED at 241.
1 out of 1 hunk FAILED -- saving rejects to file dcmdata/libsrc/dcdatset.cc.rej

Cause: Library version mismatch - patch doesn’t match the source code.Solution 1 - Verify versions match:

source seed.conf
source $CONFIG_VERSION_SET
echo "DCMTK version: $DCMTK_VERSION"
ls patch/dcmtk-*.patch

Ensure patch filename matches library version exactly.Solution 2 - Use correct version set:

./seed.sh
# Select the version set that matches available patches
# Default: version-set-8.8

Solution 3 - Create new patch: If using a newer library version, you’ll need to create a new patch. See Patching Dependencies.Diagnostic commands:

# Test patch without applying
cd $SRC_DCMTK
patch --dry-run -p1 -i $PATCH_DIR/dcmtk-3.6.5_miele-easy-8.4.62.patch

# View rejected hunks
cat dcmdata/libsrc/dcdatset.cc.rej

OpenSSL version errors with DCMTK

Error message:

Undefined symbols for architecture arm64:
  "_EVP_PKEY_get_bits", referenced from:
      DcmTLSTransportLayer::setCertificateFromFile() in libdcmtls.a

Cause: DCMTK compiled against OpenSSL 1.1.x but system has OpenSSL 3.x linked via Homebrew.Solution - Temporarily switch OpenSSL versions:Edit build.sh and uncomment lines 577-582 during DCMTK compilation:

# In build.sh STEP_COMPILE_DCMTK section:
brew unlink openssl@3
brew link [email protected]
make $MAKE_FLAGS
brew unlink [email protected]
brew link openssl@3

Alternative - Use OpenSSL 1.1.x consistently:

# In version set file:
OPENSSL_VERSION=1.1.1w  # Use latest 1.1.x

# Ensure Homebrew has OpenSSL 1.1:
brew install [email protected]

Verification:

openssl version
# Should show: OpenSSL 1.1.1w

Python symlink issues with GLEW

Error message:

make[1]: python: No such file or directory
make[1]: *** [extensions] Error 1

Cause: GLEW’s auto/make process requires python command, but macOS only provides python3.Solution 1 - Create symlink:

# Check if python3 exists
which python3

# Create symlink (if not exists)
sudo ln -s $(which python3) /usr/local/bin/python

Solution 2 - Use Homebrew Python:

brew install python
# Homebrew creates python symlink automatically

Solution 3 - Edit GLEW Makefile:

cd $SRC_GLEW/auto
# Edit Makefile, replace 'python' with 'python3'
sed -i '' 's/python /python3 /g' Makefile
make

Verification:

python --version
# Should work without error

Permission denied errors

Error message:

mkdir: /usr/local/miele-bin: Permission denied
make: *** [install] Error 1

Cause: Trying to install to system directories without proper permissions.Solution 1 - Use user directories:

./seed.sh
# Configure directories:
# SRC: ~/src
# BLD: ~/build
# BIN: ~/miele-bin

All directories should be under your home directory.Solution 2 - Fix existing directory permissions:

# If directory exists but has wrong permissions
sudo chown -R $(whoami) /usr/local/miele-bin

Solution 3 - Create directories first:

mkdir -p ~/src ~/build ~/miele-bin

Best practice: Always use directories under $HOME to avoid permission issues.

Build fails with 'No rule to make target'

Error message:

make: *** No rule to make target 'install'.  Stop.

Cause: Configuration step was skipped or failed.Solution:

# Clean and reconfigure
cd $BLD/dcmtk-3.6.5
rm -f CMakeCache.txt

# Reconfigure
./reconfigure.sh
# Enable: Configure → DCMTK
# Enable: Build → DCMTK

./build.sh

Diagnostic commands:

# Check if CMakeCache.txt exists
ls $BLD/dcmtk-3.6.5/CMakeCache.txt

# Check if Makefile exists
ls $BLD/dcmtk-3.6.5/Makefile

Out of disk space

Error message:

No space left on device

Cause: Build and source directories consume significant space (20-30GB).Solution 1 - Check disk space:

df -h
du -sh ~/src ~/build ~/miele-bin

Solution 2 - Clean build directory:

# Remove intermediate build files (can be regenerated)
rm -rf ~/build/*

Solution 3 - Use shared sources:

./seed.sh
# Enable: "Share source directories among projects"

This reduces duplication if building multiple times.Solution 4 - Remove old timestamped builds:

# List timestamped directories
ls -d ~/src/miele-easy-*

# Remove old builds (keep most recent)
rm -rf ~/src/miele-easy-20240101_*

Xcode build fails after dependencies built

Error message:

fatal error: 'dcmtk/config/osconfig.h' file not found

Cause: Symbolic links not created or Xcode project not finding libraries.Solution 1 - Create symbolic links:

./reconfigure.sh
# Enable: Create Symbolic links
# Enable all sub-options

./build.sh

Solution 2 - Verify symlinks:

ls -la $SRC_APP/Binaries/
# Should show symlinks to all installed libraries

Solution 3 - Complete STEP 5: Follow the manual fixup steps in README.md STEP 5. Some Xcode project settings require manual configuration.Diagnostic commands:

# Check symlink targets exist
ls -la $(readlink $SRC_APP/Binaries/DCMTK)

Library version mismatch errors

Error message:

undefined reference to 'vtkRenderingCore_9_2'
expected 'vtkRenderingCore_9_0'

Cause: Mixed library versions - dependencies built with different versions than expected.Solution 1 - Use consistent version set:

./seed.sh
# Ensure all settings use the same version set
# Don't mix libraries from different version sets

Solution 2 - Rebuild all dependencies:

# Clean everything
rm -rf ~/build/*
rm -rf ~/miele-bin/*
rm -rf ~/src/miele-easy-*

# Rebuild from scratch
./reconfigure.sh
# Enable: Download, Configure, Build, Install
./build.sh

Prevention: Always build all dependencies together from the same version set.

CMake generator errors

Error message:

CMake Error: Could not create named generator Xcode

Cause: Xcode or Xcode Command Line Tools not installed.Solution 1 - Install Xcode:

# Install from Mac App Store
# Then install command line tools:
xcode-select --install

Solution 2 - Accept Xcode license:

sudo xcodebuild -license accept

Solution 3 - Switch to Unix Makefiles:

./seed.sh
# Select: Generator → Unix Makefiles

Verification:

xcode-select -p
# Should show: /Applications/Xcode.app/Contents/Developer

gsort command not found

Error message:

build.sh: line 132: gsort: command not found

Cause: GNU sort (gsort) required for macOS 10.15+, but not installed.Solution:

brew install coreutils

This installs GNU utilities including gsort.Background: build.sh:128-133 uses gsort for version comparison on macOS 10.15+, but falls back to sort on older versions.Verification:

which gsort
gsort --version

Diagnostic Commands

Check Environment

# Verify all paths
source seed.conf
source $CONFIG_VERSION_SET
echo "SRC: $SRC"
echo "BLD: $BLD"
echo "BIN: $BIN"
echo "TIMESTAMP: $TIMESTAMP"

Check Configuration

# View current settings
cat seed.conf
cat steps.conf
cat $CONFIG_VERSION_SET

Check Build Status

# List installed libraries
ls -la $BIN/

# Check specific library
ls -la $BIN/dcmtk-3.6.5/lib/
ls -la $BIN/dcmtk-3.6.5/include/

Check Source Downloads

# List downloaded sources
ls -la $SRC/

# Check if patches applied (look for .orig files)
find $SRC_DCMTK -name "*.orig" | head -5

Check Symbolic Links

# Verify all symlinks in Binaries directory
ls -la $SRC_APP/Binaries/

# Check symlink target
readlink $SRC_APP/Binaries/DCMTK

# Verify target exists
ls -la $(readlink $SRC_APP/Binaries/DCMTK)

Getting Help

Useful Information to Provide

When seeking help, include:

System information:
```
sw_vers
uname -m
xcode-select -p
```

Build configuration:

cat seed.conf
source seed.conf
echo $CONFIG_VERSION_SET

Error messages: From build log
```
tail -100 log/20240101_1530.txt
```
Steps attempted: What you’ve already tried

Resources

Miele-LXIV GitHub: https://github.com/bettar/miele-lxiv
Build logs: Check $EASY_HOME/log/ directory
Source comments: build.sh contains helpful inline documentation

Prevention Tips

Always use build logs - Capture output with script command
Build incrementally - Test one library at a time when troubleshooting
Keep backups - Save working configurations before experimenting
Use default settings - Start with version-set-8.8 before customizing
Check prerequisites - Verify all tools installed before starting
Monitor disk space - Ensure 30GB+ available before building
Read error messages - They often indicate exactly what’s wrong
Follow build order - Don’t skip configure/build/install steps

Clean Build Procedure

If all else fails, start fresh:

# 1. Remove all generated files
rm seed.conf steps.conf
rm -rf log/*

# 2. Clean build artifacts
rm -rf ~/build/miele-easy-*
rm -rf ~/miele-bin/miele-easy-*

# 3. Optionally remove sources (will re-download)
rm -rf ~/src/miele-easy-*

# 4. Start configuration from scratch
./build.sh  # Creates seed.conf
./seed.sh   # Configure settings

# 5. Download
./reconfigure.sh
# Enable: Download sources
./build.sh

# 6. Build
./reconfigure.sh  
# Enable: Configure, Build, Install
script log/$(date +%Y%m%d_%H%M).txt
./build.sh ; exit

Get Started

Setup Guide

Configuration

Dependencies

Advanced

Overview

Build Log Usage

Common Issues

Diagnostic Commands

Check Environment

Check Configuration

Check Build Status

Check Source Downloads

Check Symbolic Links

Getting Help

Useful Information to Provide

Resources

Prevention Tips

Clean Build Procedure

Build docs developers (and LLMs) love

Get Started

Setup Guide

Configuration

Dependencies

Advanced

​Overview

​Build Log Usage

​Common Issues

​Diagnostic Commands

​Check Environment

​Check Configuration

​Check Build Status

​Check Source Downloads

​Check Symbolic Links

​Getting Help

​Useful Information to Provide

​Resources

​Prevention Tips

​Clean Build Procedure

Build docs developers (and LLMs) love

Overview

Build Log Usage

Common Issues

Diagnostic Commands

Check Environment

Check Configuration

Check Build Status

Check Source Downloads

Check Symbolic Links

Getting Help

Useful Information to Provide

Resources

Prevention Tips

Clean Build Procedure