=============================================================================
BuildInfo - Build and Compilation Information on RISC OS         Version 1.01

(C) Stephen Fryatt, 2005-2025                                   18 April 2025
=============================================================================

Contents
--------

  1. Licence
  2. Introduction & Installation
  3. Usage
  4. Version History
  Updates and Contacting Me

1. Licence
----------

  BuildInfo is licensed under the EUPL, Version 1.2 only (the "Licence");
  you may not use this work except in compliance with the Licence.

  You may obtain a copy of the Licence at
  http://joinup.ec.europa.eu/software/page/eupl.

  Unless required by applicable law or agreed to in writing, software
  distributed under the Licence is distributed on an "*as is*" basis,
  *without warranties or conditions of any kind*, either express or implied.

  See the Licence for the specific language governing permissions and
  limitations under the Licence.

  The source for BuildInfo can be found on GitHub, at
  https://github.com/steve-fryatt/build-info.

2. Introduction & Installation
------------------------------

  BuildInfo is a utility to create the date and version information (build
  date and build version) needed when building software. It was created for
  use with the Desktop Development Environment (DDE), but could be useful in
  other configurations as well.

  The utility will read the current date and prompt at the command line for
  a version number, which can then be used in the build process (such as to
  be shown in an application's Program Information window). If no version is
  supplied and the Currently Selected Directory is the root of a Git
  repository (ie. the directory containing the /Git folder), then BuildInfo
  will use the current commit hash as the version string instead.

  Once the details have been collected, BuildInfo can write them to a header
  file or store them in nominated system variables before the rest of the
  build process begins.

  BuildInfo is a more generalised -- and polished -- evolution of a
  CompileDate utility that I was using back in the early 2000s for building
  C applications natively. It aims to be broadly compatible in use with the
  Linux tools that I now use when cross-compiling with the GCCSDK.

  2.1. Installation
  -----------------

  To install BuildInfo, simply ensure that the BuildInfo program is
  somewhere on Run$Path -- this can be achieved easily by placing it into
  Boot:Library.

3. Usage
--------

  BuildInfo expects the Currently Selected Directory (CSD) to be the
  directory containing the project being built, in line with the standard
  practice for DDE build scripts to start with a "*Dir <Obey$Dir>" line. For
  example

    Dir <Obey$Dir>
    BuildInfo

  It will start be reporting its own version number and build date, before
  prompting for the required version number for the build.

    BuildInfo 0.00 (17 Apr 2025)
    Enter version number (leave empty to use Git hash):

  A version number can be typed in at this point, in whatever format your
  build process expects: it is just a text string. If the field is left
  blank and Return pressed immediately, BuildInfo will look for a /Git
  folder in the CSD and attempt to identify the commit hash associated with
  HEAD. If a hash is found, this will be used as a version -- by default
  taking the first seven digits.

  Once the version number has been resolved, BuildInfo will report the
  details and then proceed to set up the build prerequisites.

    The version number is e9916c3
    The build date is 17 Apr 2025

  If only four characters were required from the commit hash, then passing
  the -digits <n> parameter when calling BuildInfo like this

    BuildInfo -digits 4

  would result in

    The version number is e991
    The build date is 17 Apr 2025

  If a version number is entered, then this will be used instead of looking
  up a commit hash. For example

    BuildInfo 0.00 (17 Apr 2025)
    Enter version number (leave empty to use Git hash): 1.23
    The version number is 1.23
    The build date is 17 Apr 2025

  The actions which are taken after this point will depend on the parameters
  passed to the command from the build script. Any combination of the
  options descibed in the following sections may be carried out.

  3.1. System variables
  ---------------------

  BuildInfo can set two system variables to hold the date and version as
  displayed on the command line. These are specified using the -datevar
  <name> and -versionvar <name> parameters. For example

    BuildInfo -datevar Build$Date -versionvar Build$Version

  would set Build$Date to contain the date (such as "17 Apr 2025") and
  Build$Version to contain the version (such as "e9916c3" or "1.23").

  3.2. C Header file
  ------------------

  A C header file can be written out, defining the constants BUILD_INFO_DATE
  and BUILD_INFO_VERSION. The name of the file, relative to the CSD, is
  specified using the -cheader <path> parameter. For example, the command

    BuildInfo -cheader h.buildinfo

  would result in the h.buildinfo file being written containing

    /* h.buildinfo
     *
     * Date of build and version for use as constants.
     * Auto-generated at build time by BuildInfo.
     */
    
    #define BUILD_INFO_DATE "17 Apr 2025"
    #define BUILD_INFO_VERSION "e9916c3"

4. Version History
------------------

  This is a complete list of all the changes made to the publicly released
  versions of BuildInfo.

  4.1. 1.00 (18 Apr 2025)
  -----------------------

  Initial public release.

  4.2. 1.01 (18 Apr 2025)
  -----------------------

  Update to initial public release.

  * Create trimmed commit hashes from the start of the number, in line with
    common practice.

Updates and Contacting Me
-------------------------

  If you have any comments about BuildInfo, or would like to report any bugs
  that you find, you can email me at the address below.

  Updates to BuildInfo and more software for RISC OS computers can be found
  on my website at http://www.stevefryatt.org.uk/risc-os.

  Stephen Fryatt
  email: info@stevefryatt.org.uk
