Add Linux build support and fix cross-platform compatibility

- Fix Hermes include path case sensitivity (public vs Public)
  for Linux
- Add ICU library linking required for Hermes on Linux
- Propagate C/C++ compiler settings to Hermes external project
  build
- Set CC environment variable when invoking shermes for
  consistent compiler usage
- Add Threads::Threads linking to sokol with proper platform
  handling
- Suppress C99 designator warnings for GNU/Clang compilers in
  C++ files
- Fix struct field initialization order in imgui-runtime.cpp
- Add CMake check for node_modules directory with clear error
  message
- Update README with Linux dependencies (X11, OpenGL, ICU)
- Update README with Clang compiler requirement and Node.js
  installation via snap
- Mark Linux as tested on Ubuntu 24.04.3 LTS in README
- Add commit message style guidelines to CLAUDE.md

Author: tmikov

CLAUDE.md

@@ -23,6 +23,26 @@ When implementing changes:
 
 Never commit code immediately after implementation. The user must review and test first.
 
+**⚠️ COMMIT MESSAGE STYLE**
+
+Write commit messages that are factual and technical:
+- State what was changed, not how you feel about it
+- Use objective language without emotion, opinions, or exaggeration
+- Avoid words like "awesome", "amazing", "great", "excellent", "beautiful"
+- Be concise and descriptive
+- Focus on the technical change and its purpose
+- Wrap lines at 72 characters
+
+Good examples:
+- "Add ICU library linking for Linux compatibility"
+- "Fix case-sensitive filesystem issue in Hermes includes"
+- "Pass compiler settings to Hermes external project"
+
+Bad examples:
+- "Amazing fix for the awesome Linux build!"
+- "Greatly improve the build system"
+- "Make things work better"
+
 ## Project Overview
 
 This project implements a custom React reconciler that renders to DearImGUI using Static Hermes. The goal is to use React's declarative component model and JSX syntax to describe ImGUI interfaces, while learning how React works internally.

CMakeLists.txt

@@ -3,6 +3,11 @@ project(imgui-react-runtime)
 
 set(CMAKE_CXX_STANDARD 17)
 
+# Suppress C99 designator warnings for C++ files with GCC/Clang
+if(CMAKE_CXX_COMPILER_ID MATCHES "GNU|Clang")
+    add_compile_options($<$<COMPILE_LANGUAGE:CXX>:-Wno-c99-designator>)
+endif()
+
 # Validate required variables
 if(NOT CMAKE_BUILD_TYPE)
     message(FATAL_ERROR "CMAKE_BUILD_TYPE must be set (e.g., Debug or Release)")
@@ -50,7 +55,7 @@ file(GLOB RECONCILER_FILES
 # Hermes include directories
 include_directories(${HERMES_BUILD}/lib/config)
 include_directories(${HERMES_SRC}/include)
-include_directories(${HERMES_SRC}/Public)
+include_directories(${HERMES_SRC}/public)
 include_directories(${HERMES_SRC}/API)
 include_directories(${HERMES_SRC}/API/jsi)
 

README.md

@@ -97,16 +97,16 @@ This project uses typed mode for the ImGui FFI layer (`lib/imgui-unit/`) and unt
 ### Supported Platforms
 
 - **macOS** ✅ Fully tested and supported
-- **Linux** 🔨 Expected to work with minimal changes (untested)
+- **Linux** ✅ Tested on Ubuntu 24.04.3 LTS
 - **Windows** ⏳ Coming soon (waiting for Static Hermes Windows support)
 
 ### Build Requirements
 
 You'll need:
 
-- **Node.js and npm** - For esbuild bundler and React dependencies
+- **Node.js and npm** (Node 20 or later recommended) - For esbuild bundler and React dependencies
   - macOS: `brew install node` or download from [nodejs.org](https://nodejs.org/)
-  - Linux: `apt-get install nodejs npm` or `yum install nodejs npm`
+  - Linux: `snap install node --classic` (recommended) or `apt-get install nodejs npm`
 - **C++ Compiler**
   - **Clang** (recommended) - Officially supported by Static Hermes
   - GCC also works but Clang is the tested configuration
@@ -118,6 +118,9 @@ You'll need:
 - **Ninja** - Fast build system
   - macOS: `brew install ninja`
   - Linux: `apt-get install ninja-build` or `yum install ninja-build`
+- **Graphics libraries** - Required for Sokol (window management and OpenGL rendering)
+  - macOS: (no additional packages needed)
+  - Linux: `apt-get install libx11-dev libxi-dev libxcursor-dev libgl1-mesa-dev libicu-dev`
 
 **That's it!** The project has **no other dependencies**. The CMake build process automatically downloads and builds Static Hermes on first configure.
 
@@ -132,7 +135,12 @@ cd imgui-react-runtime
 npm install
 
 # Configure (downloads and builds Hermes automatically on first run)
-cmake -B cmake-build-debug -DCMAKE_BUILD_TYPE=Debug -G Ninja
+# On Linux, explicitly specify Clang as the compiler:
+cmake -B cmake-build-debug -DCMAKE_BUILD_TYPE=Debug -G Ninja \
+  -DCMAKE_C_COMPILER=clang -DCMAKE_CXX_COMPILER=clang++
+
+# On macOS, Clang is the default, so just:
+# cmake -B cmake-build-debug -DCMAKE_BUILD_TYPE=Debug -G Ninja
 
 # Build all examples
 cmake --build cmake-build-debug

cmake/HermesExternal.cmake

@@ -87,6 +87,8 @@ else()
         -DCMAKE_BUILD_TYPE=Release
         -DHERMES_ENABLE_TEST_SUITE=OFF
         -DHERMES_BUILD_APPLE_FRAMEWORK=OFF
+        -DCMAKE_C_COMPILER=${CMAKE_C_COMPILER}
+        -DCMAKE_CXX_COMPILER=${CMAKE_CXX_COMPILER}
     )
 
     # Add Hermes as external project

cmake/hermes.cmake

@@ -89,7 +89,7 @@ function(hermes_compile_native)
     # Create custom command
     add_custom_command(
         OUTPUT ${ARG_OUTPUT}
-        COMMAND ${SHERMES} ${COMPILER_FLAGS}
+        COMMAND ${CMAKE_COMMAND} -E env CC=${CMAKE_C_COMPILER} ${SHERMES} ${COMPILER_FLAGS}
         DEPENDS ${ARG_SOURCES} ${ARG_DEPENDS}
         WORKING_DIRECTORY ${ARG_WORKING_DIRECTORY}
         COMMENT ${ARG_COMMENT}

cmake/react-imgui.cmake

@@ -75,6 +75,11 @@ function(add_react_imgui_app)
         ${CMAKE_CURRENT_SOURCE_DIR}/*.js
     )
 
+    # Check if npm install has been run
+    if(NOT EXISTS "${CMAKE_SOURCE_DIR}/node_modules")
+        message(FATAL_ERROR "node_modules/ directory not found. Please run 'npm install' in the project root before building.")
+    endif()
+
     # Build dependency list
     set(REACT_UNIT_DEPS
         ${RECONCILER_FILES}

external/sokol/CMakeLists.txt

@@ -34,10 +34,11 @@ else ()
     add_library(sokol STATIC sokol.c ${SOKOL_HEADERS})
     if (CMAKE_SYSTEM_NAME STREQUAL Linux)
         target_link_libraries(sokol INTERFACE X11 Xi Xcursor GL dl m)
-        find_package(Threads)
-        target_link_libraries(sokol PUBLIC Threads::Threads)
     endif ()
 endif ()
+
+find_package(Threads REQUIRED)
+target_link_libraries(sokol PUBLIC Threads::Threads)
 target_link_libraries(sokol PUBLIC cimgui)
 target_include_directories(sokol INTERFACE ${CMAKE_CURRENT_SOURCE_DIR})
 target_compile_definitions(sokol PUBLIC ${SOKOL_DEFINES})

lib/imgui-runtime/CMakeLists.txt

@@ -16,5 +16,6 @@ target_link_libraries(imgui-runtime
     sokol stb cimgui imgui-unit jslib-unit
     $<$<CONFIG:Release>:hermesvm_a jsi boost_context>
     $<$<CONFIG:Debug>:hermesvm>
+    $<$<PLATFORM_ID:Linux>:icuuc icui18n icudata>
 )
 target_include_directories(imgui-runtime INTERFACE ${CMAKE_CURRENT_SOURCE_DIR})

lib/imgui-runtime/imgui-runtime.cpp

@@ -142,7 +142,7 @@ extern "C" const simgui_image_t *image_simgui_image(int index) {
 }
 
 static void app_init() {
-  sg_desc desc = {.context = sapp_sgcontext(), .logger.func = slog_func};
+  sg_desc desc = {.logger.func = slog_func, .context = sapp_sgcontext()};
   sg_setup(&desc);
   simgui_setup(simgui_desc_t{});