From f725b1ab656885e7e4765ddcd9e21a9a502e924e Mon Sep 17 00:00:00 2001 From: Harvey Fong Date: Fri, 22 Aug 2025 15:40:28 +0000 Subject: [PATCH] added claude helper md and dependency list --- README.md | 14 ++++++ do_no_spiral.md | 126 ++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 140 insertions(+) create mode 100644 do_no_spiral.md diff --git a/README.md b/README.md index ef780e6..4a2995f 100644 --- a/README.md +++ b/README.md @@ -2,3 +2,17 @@ - first working + +``` +sudo apt-get install -y build-essential git cmake autotools-dev + +sudo apt install -y mesa-utils libegl-mesa0 libgl1-mesa-dri libglu1-mesa xvfb +sudo apt install zlib1g-dev libpng-dev libgl1-mesa-dev libglu1-mesa-dev + +--- +Sudo apt install git build-essential qtbase5-dev libqt5opengl5-dev libpng-dev zlib1g-dev libboost-dev curl + +sudo apt install libminizip-dev libjpeg-dev + +sudo apt install -y libtinyxml-dev +``` diff --git a/do_no_spiral.md b/do_no_spiral.md new file mode 100644 index 0000000..4aaaee5 --- /dev/null +++ b/do_no_spiral.md @@ -0,0 +1,126 @@ +# 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:** +```bash +LP3D_VERSION="2.4.9.4133" # Will need updating +LP3D_APP_VERSION="2.4.9.4133" # Will need updating +``` + +**Directory names with version:** +```bash +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." \ No newline at end of file