On including source information in your server
==============================================

OUTLINE
-------
  1. Background; server_version()
  2. Guidelines (for packagers and public server operators)
  3. Where to get version_src.h
  4. Format of version_src.h

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

The string argument can name one of the available values
or groups of values, notably,

     "major","minor","release","ext"
		components of the version number
     "string"	combined version string
     "features" list of major features
     "options"	options.h settings
     "options/DEFAULT_FG_TICKS"
		particular options.h setting
     "make"	make command line variable overrides
     "make/CPPFLAGS"
		particular make variable
     "source"	source control information

Many of these values can be overridden from version_src.h, a file
which is NOT included in version control, but rather is created
manually by whoever created the release distribution, or by your
package maintainer (if your source comes from an RPM or somesuch),
and/or automatically generated in your build environment, depending.

For values in the "source" or "make" groups, since these necessarily
come from *outside* the server sources, version_src.h is the ONLY
means of getting these values into your server build, and the exact
method used will vary depending on your situation.

You may also wish to control the level of detail available, perhaps
leaving some groups partially or completely uninformative.

(N.B. the content of the "options" group is determined by 
version_options.h, which is generated by version_opt_gen.pl)

GUIDELINES
----------
If you are running a public server, OR you are a package maintainer
for some OS distribution (e.g., for Debian, Red Hat) creating a
source package or binary build of the LambdaMOO server intended
to be publically available, we request that you adhere to the
following guidelines:

(1) In cases where server sources are modified significantly
    from an officially released version, i.e., beyond the
    setting of one or more options.h macros,
    the "ext" string should always be non-empty.

(2) 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:

       "vcs" = version control system, one of the following:

	   "release" -- code *is* a release tarball
	   "git" -- code is snapshot from a Git repository
	   "cvs" -- code is snapshot from a CVS repository
	   "unknown" -- source information is unavailable

       "vcs_version" = version number for Git or CVS installation
       "commit" = Git commit ID (40-character SHA1 value)
       "url" = URL of public repository

Note that if version_src.h is an empty file, these guidelines will
be automatically satisfied, see below.

WHERE TO GET version_src.h
--------------------------

(*) If your server source is from a release distribution, you should
    already have a version_src.h file that is appropriate.

(*) If you installed a source package provided with your OS
    distribution, your package maintainer should have either 
    already created version_src.h or provided the means for 
    generating it.

In either case, your version_src.h should remain adqequate so long as
your changes are limited to the various customizations allowed in
options.h.  If you go beyond this, you should delete or modify that file.

(*) If your server source is a snapshot from a Git repository,
    said repository should provide instructions on how to
    generate version_src.h from repository logs.

Most likely, you will need to symlink ./verion_hook to a provided
shell (or perl) script, which you can then modify to taste.

./version_hook, if present and executable, is invoked by GNUmakefile
on every invocation of GNU make in your source directory.  If you are
using some other version of make, you will need to invoke version_hook
by some other means, e.g., Git's checkout hook -- which admittedly
cannot capture make variable overrides, but can at least set useful
values for the "source" group.


FORMAT OF version_src.h
-----------------------
This file is a possibly-empty sequence 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

   #define VERSION_MAKEVARS(DEF) \
      DEF(<varname>,"<value>") \
      ...

   #define VERSION_SOURCE(DEF) \
      DEF(<varname>,"<value>") \
      ...

to specify the variables that show up in the "make" and "source"
groups.  Note that <varname> is not quoted but <value> is.  Also,
don't forget the trailing slashes; each of VERSION_SOURCE and
VERSION_MAKEVARS should parse as a single #define.  Finally, the "DEF"
parameter name is arbitrary as long as it is repeated verbatim in the
macro value as shown.

If version_src.h is an empty file, it will be as if the file
contained

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