On including source information in your server

Background on server_version()
./configure options
Guidelines (for packagers and public server operators)
About version.fixed and version.lastck
Format of version_src.h

Background

Within a running server instance, the built-in function server_version(), when provided a string or boolean-true argument, returns meta-information about the server build.

A non-string boolean-true value (e.g., 1) returns the entire structure of known information. A string argument narrows the result to particular subtrees or leaves, notable possibilities including:

major,minor,release,ext are particular version string components
string = combined version string
features = list of active extensions (see extensions.ac)
config group = how ./configure was run
options group = all options.h settings
make group = make command line variable overrides
source group = source control information

The groups form a hierarchy so it is also possible to address individual settings, e.g.,

options/DEFAULT_FG_TICKS = value of DEFAULT_FG_TICKS
config/args = ./configure command-line arguments
source/commit = git commit ID if built from a git repository

As of version 1.9.0, using the default configuration, if you build the main branch from the git repository or if you build from a release tarball, these fields will be populated automatically. Some groups can be suppressed via ./configure arguments.

(Historical note: The process described in the 1.8.3 master branch for setting up ways to generate version_src.h from version_hook and having a special GNUmakefile that runs version_hook has now been deprecated and superceded.)

Currently, there are two supported scenarios:

Building from a release tarball
- major.minor.release is as in version.c unless overidden by version.fixed.
- ext is set by version.fixed (usually blank) except there can be additional suffixes if source files have been edited.
- source/vcs = "release"
Release tarballs are identified by the file version.fixed being present, in which case detecting editing depends on MANIFEST being present.
Building from git:
- major.minor.release and ext are derived from the most recent repository tags of the form vN.N.Next where the N's are sequences of digits, except ext can have additional suffixes: +N if there have been that many commits since the tagged commit, and an additional ?N to indicate uncommitted source files.
- source/vcs = "git"
- source/commit is the commit id

Options for ./configure

Note that as per convention for all --enable and --with options, --enable-foo=yes is equivalent to --enable-foo, while --disable-foo is equivalent to --enable-foo=no

--enable-svf-source include the "source" group [default]
--disable-svf-source exclude the "source" group
--enable-svf-make include the "make" group
--disable-svf-make exclude the "make" group
The "make" group relies on GNU-specific features, notably the setting of MAKEOVERRIDES and the ability to do ${subst ...} in makefiles, to create version_make.h. Therefore the default is 'yes' or 'no' according as GNU make is in use or not.
--enable-svf-diff=[yes|!|?=no]
--disable-svf-diff = --enable-svf-diff=no
check for uncommitted/modified source, the general principle being that if sources have been modified from the commit that was actually released, something should appear in the version string to warn about this.
- yes = compute hash and compare
- ? = do not and append '?' to ext (i.e., assume uncommitted and modified)
- ! = do not and leave ext alone (i.e., assume committed / not modified meaning you are lying about having checked, or promising you have not modified anything that matters, or have some other way of checking)
The default is '?' if we cannot actually compute hashes (e.g., due to git not being installed and no sha1 program), and otherwise 'yes'.
VERSION_EXT=prefix makes the ext component include a prefix, e.g., VERSION_EXT=alpha could be used to make an alpha release.

The combination of VERSION_EXT=string --enable-svf-diff=! ensures that ext will be a specific string and nothing else.

(The content of the "options" group is determined by version_options.h, which is generated by ./configure based on the content of options.ac and any options declared in extensions)

Guidelines

If you are running a public server OR you are a package maintainer for some OS distribution, creating a source package or binary build of the LambdaMOO server intended to be publically available, we request adherence to the following guidelines:

In cases where server sources are modified significantly from an officially released version, i.e., beyond changing the defaults for one or more options.h macros, the "ext" string should be nonempty (and should include a "?" if source does not correspond to a commit in some repository).
It is not required that values in the "source" group be provided, but where provided they should be truthful. The following values are currently recognized/defined:
- url = URL of public repository
- vcs = version control system, one of the following:
  - release -- code is a release tarball
  - git -- code is from a git repository
  - unknown -- source information is unavailable
- vcs_version = version number (for git or whatever other version control software is in use)
- commit = Git commit ID (40-character SHA1 value) (and likewise if this notion is meaningful in other VC systems)

Having version_src.h and version_make.h be empty files will satisfy these guidelines, see below.

(At one time, it was imagined we would need to support vcs=cvs for a CVS repository, but since Sourceforge stopped supporting CVS in 2017, and nobody we know maintains one, don't expect to see this any time soon).

About `version.fixed` and `version.lastck`

Both of these files are shell scripts.

version.lastck contains any information extracted from git, and results of the last treediff if svf-diff is enabled. It is updated by config.status and, if it changes, it is used to write a new version_src.h.

version.fixed, if present, indicates to ./configure that this is a release tarball, includes various settings that do not change, and indicates that git should not be used to determine the version number. It can contain any of the following shell variable settings

    moo_MAJOR
    moo_MINOR
    moo_RELEASE
    moo_EXT
    moo_DEFSRC
    moo_UHASH_RELEASE

FORMAT OF version_src.h and version_make.h

These files are possibly-empty sequences of #defines.

    #define VERSION_MAJOR <number>
    #define VERSION_MINOR <number>
    #define VERSION_RELEASE <number>
    #define VERSION_EXT "<string>"

to override various components of the version string set in version.c, and

    #define VERSION_XTLIST(DEF) DEF("<extension>")...
    #define VERSION_SOURCE(DEF) DEF(<property>,"<value>")...
    #define VERSION_CONFIG(DEF) DEF(<property>,"<value>")...
    #define VERSION_MAKEVARS(DEF) DEF(<varname>,"<value>")...

to specify the "features" list and the values that show up in the "source", "config" and "make" groups. (Note: VERSION_MAKEVARS is in version_make.h, everything else is in version_src.h)

The property name is not quoted but value is. Also, the group settings will be split across multiple lines with trailing slashes, but each should parse as a single #define. Finally, the parameter name "DEF" is completely arbitrary, it just needs to show up verbatim in the macro value as shown.

If version_src.h and version_make.h are empty files, it will be as if they (collectively) contained

    #define VERSION_EXT "+?_ad_hoc_??"
    #define VERSION_SOURCE(DEF)  DEF(vcs,"unknown")

8.3 KiB Raw Permalink Blame History