[
https://issues.apache.org/jira/browse/GEODE-10518?page=com.atlassian.jira.plugin.system.issuetabpanels:all-tabpanel
]
Jinwoo Hwang updated GEODE-10518:
---------------------------------
Fix Version/s: 2.0.0
(was: 2.1.0)
> Documentation Updates for Jakarta EE 10 Migration
> -------------------------------------------------
>
> Key: GEODE-10518
> URL: https://issues.apache.org/jira/browse/GEODE-10518
> Project: Geode
> Issue Type: Improvement
> Reporter: Jinwoo Hwang
> Assignee: Jinwoo Hwang
> Priority: Major
> Fix For: 2.0.0
>
>
> h2. Summary
> The current Docker-based documentation preview environment fails to build on
> ARM64 architectures, preventing contributors using modern platforms from
> previewing Apache Geode documentation locally.
> h2. Description
> h3. Problem Statement
> The current Docker-based documentation preview environment fails to build on
> ARM64 architectures, preventing contributors using modern platforms from
> previewing Apache Geode documentation locally. This creates a significant
> barrier to documentation contributions and limits the diversity of platforms
> that can be used for development.
> h3. Platforms Affected
> The issue impacts an increasingly large segment of the contributor base:
> *Apple Silicon Macs:*
> * MacBook Pro M1/M2/M3/M4
> * MacBook Air M1/M2/M3
> * Mac Mini M1/M2/M3
> * iMac M1/M3/M4
> * Mac Studio M1 Max/Ultra, M2 Max/Ultra
> *Cloud Platforms:*
> * AWS Graviton (EC2 instances: t4g, m6g, c6g, r6g families)
> * Azure ARM-based VMs
> * Oracle Cloud Ampere instances
> *Other ARM64 Systems:*
> * Linux workstations with ARM64 processors
> * Development containers on ARM64 hosts
> * Raspberry Pi 4/5 (64-bit OS)
> h3. Current Behavior
> When attempting to build the documentation preview Docker image on ARM64
> systems:
> {code:bash}
> cd dev-tools/docker/docs
> ./preview-user-guide.sh
> {code}
> The build fails during Ruby gem installation with errors similar to:
> {noformat}
> Building native extensions. This could take a while...
> ERROR: Error installing libv8:
> ERROR: Failed to build gem native extension.
> libv8 requires python 2 to be installed in order to build
> Gem::Ext::BuildError: ERROR: Failed to build gem native extension
> {noformat}
> Or linker errors on macOS:
> {noformat}
> ld: Assertion failed: (targetAtom != NULL), function Fixup, file ld.hpp, line
> 1094.
> clang++: error: linker command failed with exit code 1
> {noformat}
> h3. Root Cause Analysis
> The documentation build system uses Bookbinder, a Ruby-based static site
> generator that has the following dependency chain:
> {noformat}
> bookbindery (10.1.18)
> └── therubyracer (0.12.3)
> └── libv8 (3.16.14.19)
> └── V8 JavaScript Engine (2013 vintage)
> {noformat}
> *Technical Issues:*
> # *{{libv8}}* gem version {{3.16.14.19}} was released in 2013, predating
> ARM64 architecture support
> # Pre-compiled binaries only exist for x86_64 platforms
> ({{{}libv8-3.16.14.19-x86_64-linux{}}})
> # No pre-compiled ARM64 binaries are available
> ({{{}libv8-3.16.14.19-arm64-linux{}}} does not exist)
> # Source compilation fails due to:
> ## Incompatible build scripts requiring deprecated Python 2
> ## V8 source code from 2013 not designed for ARM64 architecture
> ## Modern ARM64 toolchains incompatible with legacy build system
> ## Architecture-specific assembly code that doesn't support ARM64
> h3. Impact Assessment
> h4. Contributor Experience
> *Current Friction Points:*
> * Contributors with ARM64 systems cannot preview documentation changes
> locally
> * Must rely on CI/CD pipeline builds to see rendered output
> * Significantly slower feedback loop for documentation improvements
> * Discourages documentation contributions from affected platforms
> * Creates inequality in contributor experience based on hardware architecture
> h4. Market Trends
> The impact is growing as ARM64 adoption accelerates:
> *Apple Silicon Market Share:*
> * 100% of new Macs sold since November 2020 are ARM64-based
> * Estimated 40%+ of active Mac developer base on Apple Silicon (as of 2024)
> * Trend continuing with all future Mac releases
> *Cloud Infrastructure:*
> * AWS Graviton instances offer 40% better price/performance ratio
> * Many organizations migrating to ARM64 cloud instances
> * CI/CD systems increasingly using ARM64 runners for cost savings
> *Developer Preferences:*
> * New developers joining the project are more likely to have ARM64 systems
> * ARM64 adoption in developer community expected to exceed 50% by 2026
> h3. Scope of Issue
> h4. Files Affected
> The issue is isolated to the documentation preview tooling:
> {noformat}
> dev-tools/docker/docs/
> ├── Dockerfile # Base image platform not specified
> ├── preview-user-guide.sh # Docker commands lack platform specification
> └── README.md # No ARM64 compatibility notes
> {noformat}
> h4. User Workflows Impacted
> # *Local Documentation Preview:* Primary use case - completely broken
> # *Documentation Development:* Cannot iterate quickly on doc changes
> # *Contributor Onboarding:* New contributors on ARM64 hit immediate roadblock
> # *Documentation Reviews:* Reviewers on ARM64 cannot verify changes locally
> h4. Workarounds Currently Required
> Contributors on ARM64 platforms must resort to:
> *Option 1: Wait for CI/CD*
> * Push changes to remote branch
> * Wait for CI pipeline to build documentation
> * View in CI artifacts or deployed preview
> * Iteration time: 10-30 minutes per change
> *Option 2: Use Remote x86_64 System*
> * SSH to x86_64 server or VM
> * Set up complete development environment remotely
> * Increases complexity and resource requirements
> *Option 3: Run x86_64 VM Locally*
> * VMware/Parallels/UTM virtual machine
> * Resource intensive (requires 4-8GB RAM for VM)
> * Nested virtualization performance penalty
> * Additional licensing costs (for commercial VM software)
> *Option 4: Read Raw Markdown*
> * No styling, navigation, or final rendering
> * Cannot verify cross-references or generated content
> * Unsuitable for quality assurance
> ----
> h2. Benefits of Fixing This Issue
> h3. Improved Contributor Inclusivity
> * *Removes barrier to entry* for ARM64 users wanting to contribute
> documentation
> * *Levels the playing field* - all contributors have same local preview
> capabilities
> * *Encourages participation* from diverse hardware platforms
> * *Reduces frustration* for new contributors encountering immediate
> technical blockers
> h3. Faster Documentation Iteration
> * *Immediate feedback* on documentation changes (seconds vs. minutes)
> * *Increased productivity* with quick preview-edit-preview cycles
> * *Better quality* documentation through easier local testing
> * *Reduced CI load* from fewer "preview only" commits
> h3. Future-Proofing
> * *Aligns with industry trends* toward ARM64 adoption
> * *Prepares for majority-ARM64 future* in developer ecosystem
> * *Reduces technical debt* before problem impacts more contributors
> * *Demonstrates project modernization* and attention to contributor
> experience
> h3. Cost Efficiency
> * *Lower cloud costs* for contributors using ARM64 cloud instances
> * *Better resource utilization* - no need for x86_64 VMs or remote systems
> * *Reduced mental overhead* - one consistent workflow across platforms
> h3. Community Growth
> * *Attracts new contributors* who might otherwise be turned away
> * *Retains existing contributors* who upgrade to ARM64 hardware
> * *Improves project reputation* as being contributor-friendly
> * *Demonstrates commitment* to modern development practices
> ----
> h2. Reproduction Steps
> h3. Environment
> * *Platform:* ARM64 (Apple Silicon Mac, AWS Graviton, or ARM64 Linux)
> * *OS:* macOS 14+ or Linux (Ubuntu 22.04+)
> * *Docker:* Docker Desktop 4.0+ (Mac) or Docker Engine 20.10+ (Linux)
> * *Architecture:* {{uname -m}} returns {{arm64}} or {{aarch64}}
> h3. Steps to Reproduce
> {code:bash}
> # 1. Clone Apache Geode repository
> git clone https://github.com/apache/geode.git
> cd geode
> # 2. Navigate to documentation Docker setup
> cd dev-tools/docker/docs
> # 3. Attempt to run preview script
> ./preview-user-guide.sh
> {code}
> h3. Expected Result
> * Docker image builds successfully
> * Documentation is compiled by Bookbinder
> * Web server starts on port 9292
> * Documentation is accessible at {{[http://localhost:9292/docs/guide/115/]}}
> h3. Actual Result
> Build fails during {{libv8}} gem installation with native extension
> compilation errors.
> *Error output includes:*
> {noformat}
> ERROR: Error installing libv8:
> ERROR: Failed to build gem native extension.
> /usr/local/bundle/gems/libv8-3.16.14.19/ext/libv8/builder.rb:86:in
> `setup_python!':
> libv8 requires python 2 to be installed in order to build (RuntimeError)
> {noformat}
> And/or:
> {noformat}
> ld: Assertion failed: (targetAtom != NULL)
> clang++: error: linker command failed with exit code 1
> make: *** [preparser] Error 1
> {noformat}
> ----
> h2. Additional Context
> h3. Related Technologies
> *Docker Multi-Platform Support:*
> Docker supports building and running containers for different architectures
> through:
> * {{--platform}} flag for explicit architecture specification
> * QEMU emulation for cross-architecture execution
> * BuildKit multi-platform builds
> *Ruby Gem Ecosystem:*
> * RubyGems supports platform-specific binary gems
> * Native extensions require compilation for each platform
> * Pre-compiled binaries significantly speed up installation
> * Legacy gems may not have ARM64 binaries available
> h3. Dependency Analysis
> *Gem Versions in Use:*
> {noformat}
> bookbindery: 10.1.18 (last updated 2019)
> therubyracer: 0.12.3 (last updated 2016, unmaintained)
> libv8: 3.16.14.19 (last updated 2013, V8 from Chrome 28)
> {noformat}
> *Available Pre-compiled Platforms:*
> {noformat}
> ✓ libv8-3.16.14.19-x86_64-linux
> ✓ libv8-3.16.14.19-x86_64-darwin
> ✓ libv8-3.16.14.19-x86-linux
> ✗ libv8-3.16.14.19-arm64-linux (does not exist)
> ✗ libv8-3.16.14.19-aarch64-linux (does not exist)
> {noformat}
> h3. Alternatives Considered (for context only)
> This section documents options that were considered but are not part of the
> proposed solution:
> *Alternative A: Native Ruby Installation*
> * Requires local Ruby 2.6.x installation
> * Requires Python 2 installation
> * Requires build tools (gcc, make, etc.)
> * Still fails to compile {{libv8}} on ARM64
> * Not viable on ARM64 platforms
> *Alternative B: Update to Modern Gems*
> * Would require replacing {{therubyracer}} with {{mini_racer}}
> * Would require updating {{bookbindery}} or replacing with modern tool
> * Large scope - affects entire documentation toolchain
> * Risk of breaking existing documentation builds
> * Separate major effort beyond this issue's scope
> *Alternative C: Use Remote x86_64 Systems*
> * Does not solve the local preview problem
> * Adds complexity and resource requirements
> * Not a real fix, just a workaround
> ----
> h2. Environment Details
> h3. Confirmed Failing Platforms
> *Tested and Confirmed Failing:*
> * macOS 14.x on Apple M1/M2/M3 (arm64)
> * Ubuntu 22.04 on AWS Graviton t4g instances (aarch64)
> * Debian 12 on ARM64 (aarch64)
> h3. Working Platforms
> *Known Working (for comparison):*
> * macOS on Intel processors (x86_64)
> * Ubuntu/Debian/RHEL on Intel/AMD processors (x86_64)
> * Windows 11 on Intel/AMD with WSL2 (x86_64)
> ----
> h2. Success Criteria
> When this issue is resolved, the following should be true:
> # *Build Success:* Documentation preview Docker image builds without errors
> on ARM64 platforms
> # *Functionality:* Preview server starts and serves documentation on ARM64
> systems
> # *Performance:* Build and runtime performance is acceptable (within 2x of
> native)
> # *Compatibility:* Existing x86_64 platforms continue to work without
> regression
> # *Documentation:* Build process and platform requirements are clearly
> documented
> ----
> h2. References
> h3. External Links
> * [Docker Multi-Platform
> Builds|https://docs.docker.com/build/building/multi-platform/]
> * [RubyGems Platform Support|https://guides.rubygems.org/platforms/]
> * [libv8 Gem on RubyGems|https://rubygems.org/gems/libv8/versions/3.16.14.19]
> * [Bookbinder Documentation|https://github.com/pivotal-cf/bookbinder]
> * [Apple Silicon Migration
> Guide|https://developer.apple.com/documentation/apple-silicon]
> h3. Related Community Discussions
> * Apache Geode mailing list discussions about ARM64 support
> * GitHub Issues: Search for "ARM64", "Apple Silicon", "M1" in apache/geode
> repository
> * Developer community feedback on documentation workflow pain points
> h3. Market Data
> * [Apple Silicon Mac Sales Data|https://www.apple.com/newsroom/]
> * [AWS Graviton Performance Analysis|https://aws.amazon.com/ec2/graviton/]
> * [ARM Architecture Adoption
> Trends|https://www.arm.com/markets/computing-infrastructure]
> ----
>
> h2. Notes
> h3. Constraints
> * Must maintain backward compatibility with existing x86_64 workflows
> * Should not require changes to {{geode-docs}} content or structure
> * Should not require updates to Ruby gem versions or dependencies
> * Must work with existing {{bookbindery}} toolchain
> * Should not introduce significant performance regressions
> h3. Testing Requirements
> * Test on multiple ARM64 platforms (macOS, Linux)
> * Verify no regression on x86_64 platforms
> * Measure build time and runtime performance
> * Validate documentation renders correctly
> * Test with both script and manual Docker commands
> h3. Documentation Requirements
> * Update {{README.md}} in {{dev-tools/docker/docs}} with platform
> compatibility information
> * Add troubleshooting section for common ARM64 issues
> * Document performance expectations on emulated platforms
> * Include examples for both x86_64 and ARM64 platforms
> ----
> h2. Affected Stakeholders
> * *Documentation Contributors:* Primary beneficiaries, gain ability to
> preview locally
> * *Project Maintainers:* Reduced support burden for documentation preview
> issues
> * *New Contributors:* Smoother onboarding experience, fewer technical
> barriers
> * *Review Team:* More reviewers can verify documentation changes locally
> * *Community Members:* Improved documentation quality through easier
> contributions
> ----
> h2. Timeline Considerations
> h3. Urgency Factors
> * ARM64 adoption rate accelerating (40%+ of Mac developers as of 2025)
> * Problem affects increasing percentage of contributor base over time
> * Simple fix available (platform specification in Docker commands)
> * Low risk of introducing regressions
> h3. Impact If Not Fixed
> * Continued exclusion of ARM64 users from documentation contributions
> * Growing technical debt as ARM64 becomes dominant platform
> * Negative perception of project as not contributor-friendly
> * Lost documentation contributions from affected users
> * Increased support burden answering "why doesn't this work on my Mac?"
> ----
>
--
This message was sent by Atlassian Jira
(v8.20.10#820010)
