Summary

A build of a development tree says which release it is, and nothing about which commit of it: two of them are indistinguishable from the inside. CRuby answers this with RUBY_REVISION, and reads it out of the repository the source sits in. This defines MRUBY_REVISION the same way. The diff adds lines and changes none.

$ ./build/host/bin/mruby -e 'p MRUBY_REVISION'
"e9fe070e1ac0ec8e29007be5c97dc40f023f8315"

Naming the revision in MRUBY_DESCRIPTION follows separately.

Changes

What is defined

Modelled on CRuby's version.c, which keeps the whole hash in the constant and the abbreviation for what a version string prints:

Where it comes from, and what a commit costs to rebuild

The build writes what it read to a generated mruby/revision.h under the build directory's include, which src/version.c alone includes. One object is compiled with the revision, so a commit recompiles that one and relinks:

$ git commit --allow-empty -m ...
$ rake
GEN   build/host/include/mruby/revision.h
CC    src/version.c -> build/host/src/version.o
AR    build/host/lib/libmruby.a
LD    build/host/bin/mrdb
LD    build/host/bin/mirb
LD    build/host/bin/mruby
LD    build/host/bin/mruby-strip

The header is rewritten only where its content changed, so a build that follows no commit leaves version.o alone as well, and a second rake is a no-op.

The repository is asked with what redirects git to another one (GIT_DIR and its fellows) taken out of its environment, -C not outranking them: a rake run from a hook, from a git rebase --exec or from a git bisect run has them set for a repository of its own, and would otherwise name a commit this source never sat at. A tree with no .git of its own is not asked about at all, for the same reason: mruby vendored into a project is not at the project's commit.

Source releases

A release has no repository to ask, so it carries the answer instead. .revision holds the $Format:%H$ placeholder in the repository and the commit hash in whatever git archive writes out of it (.gitattributes, export-subst), which is what .github/workflows/release.yml cuts its tarballs with, and what GitHub's own "Source code" archives are made with, so both carry it without a workflow step. Verified end to end on an extracted archive with no .git at all:

$ cat .revision
e9fe070e1ac0ec8e29007be5c97dc40f023f8315
$ rake && ./build/host/bin/mruby -e 'p MRUBY_REVISION'
"e9fe070e1ac0ec8e29007be5c97dc40f023f8315"

Naming a revision by hand

A package built from a source drop can read neither, and may know the revision anyway. The generated header's defines are guarded, so a build config's own answer wins over what was read rather than colliding with it. doc/guides/mrbconf.md documents the pair:

conf.defines << 'MRUBY_REVISION=\"0123456789\"'
conf.defines << 'MRUBY_FULL_REVISION=\"0123456789abcdef0123456789abcdef01234567\"'

Where there is still no revision to read

A tree that is neither a checkout nor an archive cut from one, with nothing named by hand either, has nothing to say, and mruby/version.h makes it "HEAD", the way CRuby's version.c does:

#ifndef MRUBY_REVISION
#define MRUBY_REVISION "HEAD"
#endif
#ifndef MRUBY_FULL_REVISION
#define MRUBY_FULL_REVISION MRUBY_REVISION
#endif

A build driven by rules other than the ones under tasks/ writes no header at all, so src/version.c asks for it through __has_include and takes the same answer where the compiler cannot tell it is there.

The amalgam has no generated header to include, so it carries both revisions it was generated from as defines in mruby.h, ahead of the version.h that reads them.

Behaviour

MRUBY_REVISION is a new global constant. Nothing that was already defined changes: MRUBY_VERSION, MRUBY_RELEASE_NO, MRUBY_RELEASE_DATE, MRUBY_DESCRIPTION and MRUBY_COPYRIGHT read as they did.

Size

.text of bin/mruby for the five build_config/ci/gcc-clang.rb builds, size -A:

All of it is mrb_init_version defining one constant more: version.o .text 285 → 334 (mrb_init_version itself 285 → 334). The hash is another 48 bytes of .rodata (40 characters, a NUL, padding), and the constant's name 15.

Testing

test/t/version.rb asks that the constant is a frozen string, the whole commit hash where the build read one and "HEAD" where it did not.

Environment

The compile line each build actually used for src/string.c, with -MMD -c, the -I and the -o dropped. cxx_abi is gcc -x c++, g++ only linking:

bintest      gcc -std=gnu99 -g -O3 -Wall -Wundef -Werror-implicit-function-declaration -Wwrite-strings -DMRB_GC_FIXED_ARENA -DMRB_USE_BIGINT -DMRB_USE_COMPLEX -DHAVE_MRUBY_ENCODING_GEM -DMRB_UTF8_STRING -DHAVE_MRUBY_IO_GEM -DMRB_USE_RATIONAL -DHAVE_MRUBY_REGEXP_GEM -DMRB_USE_SET -DMRB_USE_TASK_SCHEDULER -DMRB_USE_DEBUG_HOOK

ascii-ctype  gcc -std=gnu99 -g -O3 -Wall -Wundef -Werror-implicit-function-declaration -Wwrite-strings -DMRB_USE_ASCII_CTYPE -DMRB_USE_BIGINT -DMRB_USE_COMPLEX -DHAVE_MRUBY_ENCODING_GEM -DMRB_UTF8_STRING -DHAVE_MRUBY_IO_GEM -DMRB_USE_RATIONAL -DHAVE_MRUBY_REGEXP_GEM -DMRB_USE_SET -DMRB_USE_TASK_SCHEDULER

byte-string  gcc -std=gnu99 -g -O3 -Wall -Wundef -Werror-implicit-function-declaration -Wwrite-strings -DMRB_USE_BIGINT -DMRB_USE_COMPLEX -DHAVE_MRUBY_IO_GEM -DMRB_USE_RATIONAL -DHAVE_MRUBY_REGEXP_GEM -DMRB_USE_SET -DMRB_USE_TASK_SCHEDULER

cxx_abi      gcc -g -O3 -Wall -Wundef -Wwrite-strings -x c++ -std=gnu++03 -DMRB_GC_FIXED_ARENA -DMRB_USE_CXX_EXCEPTION -DMRB_USE_CXX_ABI -DMRB_USE_BIGINT -DMRB_USE_COMPLEX -DHAVE_MRUBY_ENCODING_GEM -DMRB_UTF8_STRING -DHAVE_MRUBY_IO_GEM -DMRB_USE_RATIONAL -DHAVE_MRUBY_REGEXP_GEM -DMRB_USE_SET -DMRB_USE_TASK_SCHEDULER

full-debug   gcc -std=gnu99 -g -O3 -Wall -Wundef -Werror-implicit-function-declaration -Wwrite-strings -g3 -O0 -DMRB_GC_STRESS -DMRB_USE_DEBUG_HOOK -DMRB_DEBUG -DMRB_USE_BIGINT -DMRB_USE_COMPLEX -DHAVE_MRUBY_ENCODING_GEM -DMRB_UTF8_STRING -DHAVE_MRUBY_IO_GEM -DMRB_USE_RATIONAL -DHAVE_MRUBY_REGEXP_GEM -DMRB_USE_SET -DMRB_USE_TASK_SCHEDULER

Summary by CodeRabbit

• New Features

  • Added MRUBY_REVISION, exposing the source commit revision at runtime.
  • Source builds now detect revisions from Git repositories or archived releases.
  • Revision metadata is embedded automatically in generated builds, including source archives.

• Documentation

  • Added configuration guidance for revision values, overrides, and fallback behavior.

• Tests

  • Added validation for revision availability, format, and immutability.