mkmf-lite 0.8.0 → 0.8.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 221bc258ee206eb8c19c1705bdcaa769326508d901d8f8720d1b60e7e704ca5c
-  data.tar.gz: 3383b7a19d218372b56c2e8a1938af79dcdd2b4636c4fc555069190ccfcb5cb5
+  metadata.gz: b780dd7e2e0e1b2be89941ce19c6cd891de5318b53cb199e6b3cbfead5c174be
+  data.tar.gz: 7b8afafe384f433f17b309416b24a467c488696b6b2e98560c4f2e545bfd9c77
 SHA512:
-  metadata.gz: 53fd358a2dcdab183376c2d809e4c305b5ff022a81e0aa21a75041019745194adc946e1ed54005ea74a0a17f3b7b476efc7227576ae40bf0b3533b64ebce84b6
-  data.tar.gz: 291f1e2ac0b2eb7c84501dd5d82d8309569951230f5742f712ab6951bc8bcc7e2c164e96cf944923d93b61d486e9863ccaf9413bfe00cc3b0c4ecdd41c614f12
+  metadata.gz: 1a80776330561d06936541572c984baec486bbacce69fa15bf07c3e8578981791a2769e17d94e793781f5203339b037860a5ba7d86bed1d67b65216885cde910
+  data.tar.gz: 98dc7c4df08d005d8628b4509f1b58059a2995bc321798138315d794d98ffadad2ef48b383afe5374ac66b162e8c5c9108376ceb6e2d33701e89cf596b8731ae

data/CHANGES.md

@@ -1,3 +1,11 @@
+## 0.8.1 - 30-Jun-2026
+* Improved generated C formatting for size, offset, and constant probes.
+* Simplified struct member probes to use a compile-only member check.
+* Added regression coverage for generated C, linker arguments, library names,
+  and parallel probe invocations.
+* Expanded documentation for portability, diagnostics, FFI use, and
+  memoization.
+
 ## 0.8.0 - 29-Jun-2026
 * Removed implicit Linux-style library flags from compiler probes.
 * Compile probes now use argv-style command execution and per-probe temporary

data/README.md

@@ -10,7 +10,9 @@ A light version of mkmf designed for use within programs.
 `gem cert --add <(curl -Ls https://raw.githubusercontent.com/djberg96/mkmf-lite/main/certs/djberg96_pub.pem)`
 
 ## Prerequisites
-A C compiler somewhere on your system.
+A C compiler somewhere on your system. `mkmf-lite` uses the compiler Ruby was
+configured with when possible, falling back to common compiler names on your
+`PATH`.
 
 ## Synopsis
 ```ruby
@@ -43,9 +45,80 @@ used in conjunction with FFI. Also, the source code is quite readable.
 It does not package C extensions, nor generate a log file or a Makefile. It
 does, however, require that you have a C compiler somewhere on your system.
 
-As of version 0.6.0 it memoizes the results of any checks that you make
-since they wouldn't ever change without requiring a reboot/restart of your
-server, container, etc, anyway.
+## Portability model
+Each probe generates a tiny C program in a per-probe temporary directory and
+asks Ruby's configured compiler to compile it. Boolean probes return whether
+that compile or link step succeeded. Value probes compile and run a small
+program that prints the requested integer value.
+
+The generated source is intentionally small and portable. `mkmf-lite` avoids
+assuming Linux-specific libraries or global temporary filenames, and it passes
+compiler arguments as argv-style command parts so paths with spaces can work.
+
+Unlike stdlib `mkmf`, this library does not create a `Makefile`, does not build
+an extension, does not write an `mkmf.log`, and keeps its API inside
+`Mkmf::Lite` instead of relying on top-level methods.
+
+## Diagnostics
+Boolean probes such as `have_header`, `have_func`, `have_library`, and
+`have_struct_member` are quiet by default and return `true` or `false`.
+
+Value probes such as `check_valueof`, `check_sizeof`, and `check_offsetof`
+raise `StandardError` if their generated C cannot be compiled. The exception
+message includes the compiler command, compiler stderr, and generated source so
+you can see what failed without hunting for a separate log file.
+
+## FFI examples
+Use `mkmf-lite` to decide which declarations are safe to expose through FFI:
+
+```ruby
+require 'ffi'
+require 'mkmf/lite'
+
+module LibC
+  extend FFI::Library
+  extend Mkmf::Lite
+
+  ffi_lib FFI::Library::LIBC
+
+  attach_function :getpid, [], :int if have_func('getpid', 'unistd.h')
+end
+```
+
+You can also use it to size native structs:
+
+```ruby
+class StatLayout
+  extend Mkmf::Lite
+
+  STAT_SIZE = check_sizeof('struct stat', 'sys/stat.h')
+  UID_OFFSET = check_offsetof('struct stat', 'st_uid', 'sys/stat.h')
+  HAS_BIRTHTIME = have_struct_member('struct stat', 'st_birthtime', 'sys/stat.h')
+end
+```
+
+For libraries installed outside the compiler's default include path, pass
+include directories to probes that accept them:
+
+```ruby
+class LocalHeader
+  extend Mkmf::Lite
+
+  HAVE_FOO = have_header('foo.h', '/usr/local/include')
+  FOO_VERSION = check_valueof('FOO_VERSION', 'foo.h', '/usr/local/include')
+end
+```
+
+## Memoization
+As of version 0.6.0, public probe results are memoized for the lifetime of the
+object that extends `Mkmf::Lite`. The method arguments are part of the cache
+key, so `have_header('foo.h')` and `have_header('foo.h', '/usr/local/include')`
+are distinct checks.
+
+This fits the normal use case where compiler configuration, headers, and system
+libraries do not change while the Ruby process is running. If you need to probe
+again after changing the environment, create a new object or restart the
+process.
 
 ## Known Issues
 JRuby may emit warnings on some platforms.
@@ -54,7 +127,7 @@ JRuby may emit warnings on some platforms.
 Apache-2.0
 
 ## Copyright
-(C) 2010-2025 Daniel J. Berger
+(C) 2010-2026 Daniel J. Berger
 All Rights Reserved
 
 ## Warranty

data/ROADMAP.md

@@ -1,104 +1,148 @@
 # Roadmap
 
-This branch focuses on making `mkmf-lite` more platform-neutral, safer to use
-inside applications, and easier to validate across Unix-like systems. The main
-goal is to avoid FreeBSD-specific special cases where a more general portability
-improvement would solve the same problem.
-
-## 0.8.0 - Portability Foundation
-
-Keep the public API stable and harden the existing implementation.
-
-* Replace hard-coded default libraries in `cpp_libraries`.
-* Stop assuming Linux-style `rt`, `dl`, `crypt`, and `m` availability.
-* Fix the clang branch that currently emits `-Lrt`, `-Ldl`, `-Lcrypt`, and
-  `-Lm`; these are library search path flags, not library link flags.
-* Prefer Ruby's `RbConfig` values where they are appropriate, and only add
-  explicit libraries when a probe requires them.
-* Use a per-probe temporary directory instead of shared `conftest.c` and
+This branch focuses on improving `mkmf-lite` without turning it into stdlib
+`mkmf`. The guiding rule is to add clearer extension points and better
+diagnostics while preserving the small public API that existing callers use.
+
+## Released
+
+### 0.8.0 - Portability Foundation
+
+Released 29-Jun-2026.
+
+* Removed implicit Linux-style library flags from compiler probes.
+* Replaced shell-built compiler command strings with argv-style execution.
+* Used per-probe temporary directories instead of shared `conftest.c` and
   `conftest.exe` files in `Dir.tmpdir`.
-* Avoid global `Dir.chdir` during probe compilation when practical.
-* Replace shell-built compiler command strings with argv-style execution.
-* Capture compiler diagnostics internally without emitting unwanted output.
-* Add FreeBSD CI coverage, likely through Cirrus CI or a GitHub Actions
-  FreeBSD runner.
-
-## 0.9.0 - API Improvements
-
-Add clearer extension points while preserving the existing positional API.
-
-* Add keyword options for include directories, library directories, compile
-  flags, and link flags.
-* Consider examples such as:
-
-  ```ruby
-  have_header('foo.h', include_dirs: ['/usr/local/include'])
-  have_library(
-    'foo',
-    'foo_init',
-    headers: ['foo.h'],
-    lib_dirs: ['/usr/local/lib']
-  )
-  ```
-
-* Add access to the last failed compile command and diagnostics.
-* Consider a small configuration API for global defaults such as compiler,
-  include paths, library paths, and extra flags.
-* Keep memoized public probes, but document when memoization applies and how
-  callers should think about process lifetime.
-
-## 1.0.0 - Stable Contract
+* Avoided global `Dir.chdir` during probe compilation.
+* Captured compiler diagnostics internally.
+* Improved support for include directories with spaces.
+* Added FreeBSD CI coverage.
 
-Finalize the behavior expected by downstream users.
+## 0.9.0 - C Probe Correctness
 
-* Document the supported public API and compatibility expectations.
-* Remove unnecessary runtime dependencies where feasible.
-* Document compiler selection, probe memoization, error handling, and platform
-  support.
-* Keep the library focused on lightweight compile/link probes rather than
-  becoming a replacement for stdlib `mkmf`.
+Improve the generated C probes first, keeping the Ruby API stable and avoiding
+changes that could surprise existing callers.
 
-## C Probe Correctness
+### Generated C Types
 
-These improvements can land in the earliest release where they fit cleanly.
+Improve generated C for sizes, offsets, and stricter compilers.
 
-* Print `sizeof` results using `size_t` and `%zu`.
-* Print `offsetof` results with an appropriate unsigned size format.
-* Avoid casting sizes and offsets down to `int`.
-* Review function probes under stricter C modes, where implicit declarations
-  and old-style function assumptions may fail.
-* Consider compile-time assertions for probes that only need success or failure.
+Status: Done.
 
-## Dependency Reduction
+* [x] Print `sizeof` results using `size_t` and `%zu`.
+* [x] Print `offsetof` results using `size_t` and `%zu`.
+* [x] Avoid casting sizes and offsets down to `int`.
+* [x] Review `check_valueof` output formatting for constants wider than `int`.
+* [x] Keep return values as Ruby integers.
 
-Reducing dependencies is useful, but should not distract from the portability
-foundation.
+### Function Probes
 
-* Remove `ptools` if it is only needed for `File.which`.
-* Replace `File.which` with a small internal executable lookup based on
-  `ENV['PATH']`.
-* Reevaluate `memoist` after the probe and command execution behavior is stable.
+Review function detection under stricter C modes.
+
+* Avoid relying on implicit declarations.
+* Avoid old-style function assumptions where practical.
+* Keep support for checking functions with and without caller-provided headers.
+* Preserve the current boolean behavior of `have_func`.
+
+### Compile-Only Probes
+
+Prefer compile-time checks where a probe only needs success or failure.
+
+Status: Done.
 
-## Test Coverage
+* [x] Consider compile-time assertions for struct member checks.
+* [x] Keep generated source small and readable for diagnostics.
+* [x] Avoid adding platform-specific C unless no portable form exists.
 
-The test suite should exercise command construction and failure modes, not only
-successful local probes.
+### Diagnostics
 
-* Add specs for generated compiler/linker arguments.
-* Test include and library directories containing spaces.
-* Test library names with and without a leading `lib` prefix.
-* Test parallel probe invocations to catch temporary file collisions.
+Make failed probes easier to understand without printing unexpected output.
+
+* Store the last compile command, stdout, stderr, exit status, and generated C
+  source for inspection.
+* Add a public diagnostics reader with a small stable shape.
+* Keep normal boolean probes quiet by default.
+* Improve raised errors from `check_valueof`, `check_sizeof`, and
+  `check_offsetof` with captured compiler output.
+
+### Tests
+
+Broaden tests around generated C, failure modes, and platform config.
+
+* [x] Add specs for `sizeof` and `offsetof` values that should not be truncated.
+* [x] Add specs for generated compiler/linker arguments.
+* [x] Test library names with and without a leading `lib` prefix.
+* [x] Test parallel probe invocations.
 * Add mocked `RbConfig` coverage for Linux, macOS, FreeBSD, Windows/MSVC, and
   JRuby.
-* Add a regression test proving clang does not receive bogus `-Lrt`-style
-  flags.
+* Add specs for captured diagnostics from failed probes.
+
+### Documentation
+
+Document the portability model and diagnostic behavior.
 
-## Documentation
+Status: Done.
 
-Documentation should make the portability model explicit.
+* [x] Explain that probes compile tiny C programs using Ruby's configured compiler.
+* [x] Clarify how `mkmf-lite` differs from stdlib `mkmf`.
+* [x] Add FFI-oriented examples for common Unix-like use cases.
+* [x] Document memoization behavior and how it interacts with probe inputs.
 
-* Explain that probes compile tiny C programs using Ruby's configured compiler.
-* Clarify how `mkmf-lite` differs from stdlib `mkmf`.
-* Add FFI-oriented examples for common Unix-like use cases.
-* Document how to pass include and library paths for ports-installed libraries,
-  especially `/usr/local/include` and `/usr/local/lib` on FreeBSD.
+## Later
+
+### API Options
+
+Keyword arguments may be useful, but they should wait until the lower-level
+probe behavior is settled and the compatibility tradeoffs are clearer.
+
+* Add `include_dirs:` as a keyword alternative to positional include directory
+  arguments.
+* Add `lib_dirs:` for library search paths.
+* Add `cflags:` for extra compile flags.
+* Add `ldflags:` for extra link flags.
+* Keep existing positional forms compatible.
+* Make option handling consistent across `have_header`, `have_func`,
+  `have_library`, `have_struct_member`, `check_valueof`, `check_sizeof`, and
+  `check_offsetof`.
+
+Example target API:
+
+```ruby
+have_header('foo.h', include_dirs: ['/usr/local/include'])
+have_library(
+  'foo',
+  'foo_init',
+  headers: ['foo.h'],
+  lib_dirs: ['/usr/local/lib'],
+  cflags: ['-D_GNU_SOURCE']
+)
+```
+
+### Configuration
+
+Consider a small configuration API if repeated keyword arguments become noisy.
+
+* Evaluate `Mkmf::Lite.configure` for global defaults.
+* Support compiler, include directories, library directories, compile flags,
+  and link flags as possible defaults.
+* Make configuration interaction with memoized probe results explicit.
+
+### 1.0.0 - Stable Contract
+
+Finalize the behavior expected by downstream users.
+
+* Document the supported public API and compatibility expectations.
+* Document compiler selection, probe memoization, error handling, and platform
+  support.
+* Keep the library focused on lightweight compile/link probes rather than
+  becoming a replacement for stdlib `mkmf`.
+
+### Dependency Reduction
+
+Reducing dependencies is useful, but should not distract from the 0.9 API work.
+
+* Remove `ptools` if it is only needed for `File.which`.
+* Replace `File.which` with a small internal executable lookup based on
+  `ENV['PATH']`.
+* Reevaluate `memoist` after the probe and command execution behavior is stable.

data/lib/mkmf/lite.rb

@@ -16,7 +16,7 @@ module Mkmf
     extend Memoist
 
     # The version of the mkmf-lite library
-    MKMF_LITE_VERSION = '0.8.0'
+    MKMF_LITE_VERSION = '0.8.1'
 
     private
 

data/lib/mkmf/templates/check_offsetof.erb

@@ -3,9 +3,7 @@
 
 <%= headers %>
 
-int conftest_const = (int)(offsetof(<%= struct_type %>, <%= field %>));
-
 int main(){
-  printf("%d\n", conftest_const);
+  printf("%zu\n", offsetof(<%= struct_type %>, <%= field %>));
   return 0;
 }

data/lib/mkmf/templates/check_sizeof.erb

@@ -1,10 +1,9 @@
 #include <stdio.h>
+#include <stddef.h>
 
 <%= headers %>
 
-int conftest_const = (int)(sizeof(<%= type %>));
-
 int main(){
-  printf("%d\n", conftest_const);
+  printf("%zu\n", sizeof(<%= type %>));
   return 0;
 }

data/lib/mkmf/templates/check_valueof.erb

@@ -1,8 +1,15 @@
 #include <stdio.h>
+#include <stdint.h>
+#include <inttypes.h>
 
 <%= headers %>
 
 int main(){
-  printf("%d\n", <%= constant %>);
+  if ((<%= constant %>) < 0) {
+    printf("%" PRIdMAX "\n", (intmax_t)(<%= constant %>));
+  } else {
+    printf("%" PRIuMAX "\n", (uintmax_t)(<%= constant %>));
+  }
+
   return 0;
 }

data/lib/mkmf/templates/have_struct_member.erb

@@ -1,6 +1,6 @@
 <%= headers %>
 
 int main(){
-  int s = (char *)&((<%= struct_type %>*)0)-><%= struct_member %> - (char *)0;
+  (void)sizeof(((<%= struct_type %>*)0)-><%= struct_member %>);
   return 0;
 }

data/mkmf-lite.gemspec

@@ -3,7 +3,7 @@ require 'rubygems'
 Gem::Specification.new do |spec|
   spec.name       = 'mkmf-lite'
   spec.summary    = 'A lighter version of mkmf designed for use as a library'
-  spec.version    = '0.8.0'
+  spec.version    = '0.8.1'
   spec.author     = 'Daniel J. Berger'
   spec.license    = 'Apache-2.0'
   spec.email      = 'djberg96@gmail.com'

data/spec/mkmf_lite_spec.rb

@@ -14,6 +14,24 @@ require 'tmpdir'
 RSpec.describe Mkmf::Lite do
   subject { Class.new{ |obj| obj.extend Mkmf::Lite } }
 
+  def new_probe
+    Class.new{ |obj| obj.extend Mkmf::Lite }
+  end
+
+  def template_source(file)
+    File.read(File.expand_path("../lib/mkmf/templates/#{file}", __dir__))
+  end
+
+  def parallel_probe_result
+    probe = new_probe
+
+    [probe.have_header('stdio.h'), probe.check_sizeof('int'), probe.check_valueof('EOF')]
+  end
+
+  def compile_command_with_linker_arguments(probe)
+    probe.send(:build_compile_command, nil, ['-L/tmp/lib dir', '-lfoo'])
+  end
+
   let(:st_type)   { 'struct stat' }
   let(:st_member) { 'st_uid' }
   let(:st_header) { 'sys/stat.h' }
@@ -21,7 +39,7 @@ RSpec.describe Mkmf::Lite do
 
   describe 'constants' do
     example 'version information' do
-      expect(described_class::MKMF_LITE_VERSION).to eq('0.8.0')
+      expect(described_class::MKMF_LITE_VERSION).to eq('0.8.1')
       expect(described_class::MKMF_LITE_VERSION).to be_frozen
     end
   end
@@ -87,6 +105,14 @@ RSpec.describe Mkmf::Lite do
       expect(subject.have_struct_member(st_type, st_member)).to be(false)
     end
 
+    example 'have_struct_member generates a compile-only member check' do
+      source = template_source('have_struct_member.erb')
+
+      expect(source).to include('(void)sizeof(((')
+      expect(source).not_to include('(char *)&')
+      expect(source).not_to include('- (char *)0')
+    end
+
     example 'have_struct_member requires at least two arguments' do
       expect{ subject.have_struct_member() }.to raise_error(ArgumentError)
       expect{ subject.have_struct_member('struct passwd') }.to raise_error(ArgumentError)
@@ -121,6 +147,23 @@ RSpec.describe Mkmf::Lite do
       expect(value).to be_a(Integer)
       expect(value).to eq(-1)
     end
+
+    example 'check_valueof returns a wider than int integer value' do
+      char_bit = subject.check_valueof('CHAR_BIT', 'limits.h')
+      ullong_size = subject.check_sizeof('unsigned long long', 'limits.h')
+      value = subject.check_valueof('ULLONG_MAX', 'limits.h')
+
+      expect(value).to be_a(Integer)
+      expect(value).to eq((1 << (ullong_size * char_bit)) - 1)
+    end
+
+    example 'check_valueof generates portable integer formatting' do
+      source = template_source('check_valueof.erb')
+
+      expect(source).to include('#include <stdint.h>', '#include <inttypes.h>')
+      expect(source).to include('PRIdMAX', 'PRIuMAX')
+      expect(source).not_to include('printf("%d')
+    end
   end
 
   context 'check_offsetof' do
@@ -148,6 +191,14 @@ RSpec.describe Mkmf::Lite do
       expect(size1).to eq(0)
       expect(size2).to be > size1
     end
+
+    example 'check_offsetof generates size_t output formatting' do
+      source = template_source('check_offsetof.erb')
+
+      expect(source).to include('printf("%zu\\n", offsetof(')
+      expect(source).not_to include('(int)(offsetof')
+      expect(source).not_to include('printf("%d')
+    end
   end
 
   context 'check_sizeof' do
@@ -174,6 +225,14 @@ RSpec.describe Mkmf::Lite do
       expect(size).to be_a(Integer)
       expect(size).to be > 0
     end
+
+    example 'check_sizeof generates size_t output formatting' do
+      source = template_source('check_sizeof.erb')
+
+      expect(source).to include('printf("%zu\\n", sizeof(')
+      expect(source).not_to include('(int)(sizeof')
+      expect(source).not_to include('printf("%d')
+    end
   end
 
   context 'have_library' do
@@ -187,6 +246,11 @@ RSpec.describe Mkmf::Lite do
       expect(subject.have_library('nonexistent_library_xyz')).to be(false)
     end
 
+    example 'have_library accepts a leading lib prefix' do
+      expect(subject.have_library('libm')).to be(true)
+      expect(subject.have_library('libm', 'sqrt', 'math.h')).to be(true)
+    end
+
     example 'have_library with function argument returns expected boolean value' do
       expect(subject.have_library('m', 'sqrt', 'math.h')).to be(true)
       expect(subject.have_library('m', 'nonexistent_function_xyz', 'math.h')).to be(false)
@@ -229,5 +293,20 @@ RSpec.describe Mkmf::Lite do
       expect(command).not_to include('-Lrt', '-Ldl', '-Lcrypt', '-Lm')
       expect(command).not_to include('-lrt', '-ldl', '-lcrypt', '-lm')
     end
+
+    example 'build_compile_command appends linker arguments' do
+      command_with_linker_arguments = compile_command_with_linker_arguments(subject)
+
+      expect(command_with_linker_arguments).to include('-L/tmp/lib dir', '-lfoo')
+      expect(command_with_linker_arguments.index('-lfoo')).to be > command_with_linker_arguments.index('conftest.c')
+    end
+  end
+
+  describe 'parallel probe invocations' do
+    example 'run independently without temporary file collisions' do
+      results = Array.new(6) { Thread.new { parallel_probe_result } }.map(&:value)
+
+      expect(results).to all(satisfy { |header, size, value| header && size.positive? && value == -1 })
+    end
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: mkmf-lite
 version: !ruby/object:Gem::Version
-  version: 0.8.0
+  version: 0.8.1
 platform: ruby
 authors:
 - Daniel J. Berger