amalgam: write the build's defines into the generated header - #7176

Stacked on #7175, which is the first commit here. The second commit is this
PR's own change, and the diff to read is git diff <first commit>..HEAD.
Merging #7175 first leaves this one a single commit.

rake amalgam writes a mruby.h that carries none of the defines the build
was configured with. doc/guides/amalgamation.md presents the output as two
files to drop into a project, and the compile examples pass nothing but -I
and -DNDEBUG, so whatever the header does not say is a difference between
the mruby in mruby.c and the mruby the consumer compiles against.

$ MRUBY_CONFIG=minimal rake amalgam
$ cd build/minimal/amalgam && gcc -O0 -c -I. mruby.c -o mruby.o
$ nm mruby.o | grep ' U .*printf'
                 U fprintf
                 U printf
                 U snprintf

build_config/minimal.rb is three lines and one of them is
conf.cc.defines << 'MRB_NO_STDIO'. The amalgamation of the minimal build
is not a minimal mruby.

A configuration that asks for word boxing and 32-bit integers fails more
quietly. The header names neither, so the consumer gets what mruby.h picks by
default on a 64-bit host:

printf("%zu %zu\n", sizeof(mrb_value), sizeof(mrb_int));

sizeof(mrb_int) is 8 where the configuration asked for 4.
sizeof(mrb_value) agrees at 8 either way, word boxing being the default too,
which is the part that makes this hard to notice: an ABI difference that is
invisible in the size of the value the whole API passes around.

Two things kept the defines out

collect_gem_defines read @build.defines and kept the names matching
/^MRB_USE_|^MRB_UTF8_|^HAVE_MRUBY_/.

No build configuration in the tree writes to Build#defines. Every
build_config/ file that names a define writes it on a compiler, as
conf.cc.defines or through conf.compilers.each; Build#defines is written
only by gems, through spec.build.defines. So the emitted set was the gems'
contribution alone: seven defines for a default host build, none at all for
minimal.

The pattern is the second half. The defines that decide the layout of
mrb_value and mrb_state are outside it, so moving the configurations over
to conf.defines would not have been enough on its own:

What is emitted

@build.defines and @build.cc.defines, every name that is a C identifier,
NAME=VALUE split into its two halves, each wrapped in #ifndef so a consumer
passing the same define on the command line is not redefining it. The
#ifndef and the identifier check follow write_gem_cc_defines(), which
already emits a gem's own compiler defines that way.

/* Build configuration defines */
#ifndef MRB_HEAP_PAGE_SIZE
#define MRB_HEAP_PAGE_SIZE 64
#endif
#ifndef MRB_INT32
#define MRB_INT32
#endif
#ifndef MRB_WORD_BOXING
#define MRB_WORD_BOXING
#endif

A gem's contribution and a configuration's are emitted the same way. From the
header's side they are not distinguishable: MRB_USE_BIGINT arriving because
mruby-bigint is in the gembox changes mrb_state exactly as much as
MRB_NO_STDIO arriving from a configuration file.

Two kinds stay out, and the guide now says so.

• internal_defines, the list build: hold the build's own defines in a separate list #7175 introduces for what the build adds from
  its own switches. MRB_USE_CXX_ABI in the header would make it unusable from
  C, which is what mruby.c is compiled as. A consumer who wants a C++ build
  passes those defines itself, and MRB_DEBUG, which only decides whether
  mrb_assert checks, is the same kind of choice as the -DNDEBUG the guide
  already leaves to the reader.
• cxx.defines, for the same reason: the generated source is C, so a define
  written only on the C++ compiler (NN_SDK_BUILD_RELEASE in
  build_config/nintendo_switch.rb) has no business in this header.

Measurements

The default build is unchanged because build_config/default.rb names no
define of its own. Every other line is a define the build compiled with and the
consumer did not.

Testing

rake amalgam is opt-in and no normal build goes through it, so rake -m test
on the default build is unmoved at 2085 tests, 2056 OK, 29 skip, 0 KO, 0 crash.

The minimal amalgamation compiles with -I alone, the way the guide tells a
consumer to, and the stdio it used to pull in is gone:

$ MRUBY_CONFIG=minimal rake amalgam
$ grep -x '#define MRB_NO_STDIO' build/minimal/amalgam/mruby.h
#define MRB_NO_STDIO
$ cd build/minimal/amalgam && gcc -O0 -c -I. mruby.c -o mruby.o
$ nm mruby.o | grep ' U .*printf'
$

The generated mruby.c and mruby_compiler.c of the word-boxing configuration
above compile and link into a program that opens an mrb_state, loads a string
through mrb_load_string() and closes it again, which is where its sizeof
numbers come from.

Summary by CodeRabbit

• New Features

  • Generated amalgamations now include validated, deduplicated build configuration defines with safe guards.
  • Improved handling of compiler-specific configuration options across toolchains.

• Bug Fixes

  • Amalgamated builds are now verified to compile without unresolved standard I/O references.

• Documentation

  • Updated amalgamation guidance to clarify build and compiler configuration defines, including excluded compiler-selected options.