poomer-lpub3d-build/do_no_spiral.md

LPub3D Ubuntu 24.04 Build: Lessons Learned - DO NOT SPIRAL

This document records the circuitous path to building LPub3D on Ubuntu 24.04, so future updates don't repeat the same mistakes.

Summary: What Actually Works (Ground Truth)

SUCCESS INDICATORS from build log:

• Line 178: -Building lib3ds from LDView 3rdParty sources...
• Line 179: -Successfully built and copied lib3ds.a from source
• Line 184: -LDView build completed successfully using individual OSMesa projects (VERIFIED WORKING)

The working approach builds lib3ds.a from LDView's included 3rdParty sources using qmake, NOT from system libraries.

Critical Mistakes That Caused Spiraling

1. Library Assumptions (lib3ds)

WRONG: Assume system lib3ds-dev package works WRONG: Try to symlink system lib3ds-1.so to lib3ds.so
WRONG: Copy existing lib3ds.a from successful build RIGHT: Build lib3ds.a from LDView's 3rdParty/lib3ds sources using 3rdParty_3ds.pro

The Issue: Ubuntu 24.04's lib3ds lacks lib3ds_mesh_resize_vertices and lib3ds_mesh_resize_faces functions that LDView's LDExporter needs.

The Solution: LDView includes its own lib3ds sources in 3rdParty/lib3ds/ with the compatible API.

2. Manual Fix Capture Failure

Pattern: Fix issues manually during debugging, then forget to add them to script Examples:

• Created symlinks during testing but didn't add to script
• Ran dpkg-source --commit manually but didn't automate it
• Copied libraries manually but didn't script the copy process

Rule: Every manual command run during debugging MUST be added to script immediately.

3. Version Hardcoding Issues

Hardcoded values that may break with updates:

LP3D_VERSION="2.4.9.4133"  # Will need updating
LP3D_APP_VERSION="2.4.9.4133"  # Will need updating

Directory names with version:

WORK_DIR=${LPUB3D}-${LP3D_APP_VERSION}  # Creates lpub3d-2.4.9.4133

Future-proofing needed:

• Extract version from source automatically
• Don't hardcode version strings
• Make script version-agnostic

Technical Root Causes

LDView OSMesa Build Requirements

1. Individual project approach works (not subdirs)
2. Architecture detection must force TARGET_CPU=x86_64
3. All 5 libraries required:
   • libTCFoundation-osmesa.a
   • libTRE-osmesa.a
   • libLDLoader-osmesa.a
   • libLDLib-osmesa.a (with symlink libLDraw-osmesa.a)
   • libLDExporter-osmesa.a
4. lib3ds.a must be built from 3rdParty sources

Ubuntu 24.04 Specific Issues

1. stdlib.h fix: QMAKE_CFLAGS_ISYSTEM = -I in LDViewGlobal.pri
2. lib3ds API incompatibility: System package missing required functions
3. dpkg-source format: Requires upstream tarball and local change commits

Build Flow That Works

1. Install dependencies (including lib3ds-dev, libtinyxml-dev)
2. Download LDView sources (includes 3rdParty/lib3ds)
3. Apply Ubuntu 24.04 patches (stdlib.h fix)
4. Build LDView OSMesa libraries individually (5 libraries)
5. Build lib3ds.a from 3rdParty sources using qmake
6. Create libLDraw-osmesa.a symlink
7. Copy all libraries and headers
8. Create upstream tarball for dpkg-source
9. Auto-commit local changes with dpkg-source
10. Run dpkg-buildpackage

Red Flags - Stop and Reconsider

If you see these during future updates, STOP and check ground truth:

• "skipping incompatible" library errors
• "undefined reference to lib3ds_" errors
• Copying files from successful builds instead of building them
• System library compatibility assumptions
• Manual fixes not captured in script

Key Files for Future Updates

Version detection: Look at these for automatic version extraction:

• lpub3d/mainApp/version.h or similar
• .pro files with version definitions
• Git tags in lpub3d repository

Build system files:

• LDViewGlobal.pri - Ubuntu compatibility patches
• 3rdParty/lib3ds/3rdParty_3ds.pro - lib3ds build definition
• Individual OSMesa .pro files in each component directory

Success Metrics

Build is on track when you see:

• All 5 OSMesa libraries build successfully
• lib3ds.a built from 3rdParty sources
• No "undefined reference to lib3ds_" errors
• dpkg-source issues auto-resolved
• Final lpub3d24 executable created (~90MB)

Build is failing when:

• System library compatibility errors
• Missing lib3ds functions
• Symlinks to wrong libraries
• Version "..." placeholders in paths
• Manual intervention required

Final Notes

The successful build approach follows LDView's intended build system exactly as designed. Don't try to be clever with system libraries or shortcuts. The ground truth is the working build - analyze what it did, then replicate that process programmatically.

Remember: If it worked 24 hours ago, the solution exists in the successful build artifacts. Study those first before making assumptions about what needs to be "fixed."