From 8a43226e843d2f8513ab392f074669696deff8b5 Mon Sep 17 00:00:00 2001 From: Christoph Lipka Date: Tue, 11 Sep 2018 18:14:05 +0200 Subject: [PATCH] Minor update to `source/base/build.h` and related docs. --- source-doc/devutils.md | 5 +++ source/base/build.h | 80 ++++++++++++++++++++++++++++++++++++------ windows/README.md | 6 ++++ 3 files changed, 80 insertions(+), 11 deletions(-) diff --git a/source-doc/devutils.md b/source-doc/devutils.md index 375ddf3ca..238effe05 100644 --- a/source-doc/devutils.md +++ b/source-doc/devutils.md @@ -19,6 +19,11 @@ Git Utilities The newly generated `revision.txt` is _not_ intended to be committed as-is, but rather merged with the previous version manually. + - `git update-index --skip-workspace FILENAME`: Use this git command for any file that you have to + change in your workspace but don't want to include in any commits nor have it overwritten + during a reset (e.g. `source/base/build.h`, which must be edited in a Windows build environment + to placate the `BUILT_BY` mechanism). + Visual Studio 2010 Utilities ============================ diff --git a/source/base/build.h b/source/base/build.h index c793868ce..8a72f2872 100644 --- a/source/base/build.h +++ b/source/base/build.h @@ -13,7 +13,7 @@ /// @parblock /// /// Persistence of Vision Ray Tracer ('POV-Ray') version 3.8. -/// Copyright 1991-2017 Persistence of Vision Raytracer Pty. Ltd. +/// Copyright 1991-2018 Persistence of Vision Raytracer Pty. Ltd. /// /// POV-Ray is free software: you can redistribute it and/or modify /// it under the terms of the GNU Affero General Public License as @@ -55,20 +55,78 @@ /// /// @{ -// Placeholders for macros injected during automated builds - do not remove or change! -//{POV_AUTOBUILD_A} -//{POV_AUTOBUILD_B} -//{POV_AUTOBUILD_C} -//{POV_AUTOBUILD_1} -//{POV_AUTOBUILD_2} -//{POV_AUTOBUILD_3} +/// @def POV_BUILD_INFO +/// Additional version information pertaining to the build. +/// +/// This optional macro should concisely identify the target runtime environment +/// as well as the build environment used. For instance, POV-Ray for Windows, +/// 32-bit binary with SSE2 enabled, built with Visual Studio 2015, might be +/// identified as `msvc14.sse2.win32`. +/// +/// @note +/// If defined, this macro must evaluate to an ASCII string containing only +/// alphanumeric characters or dots. +/// +/// The content of this macro will be included in the binary's version string, +/// separated from the source code version by a `+` character. +/// +/// The intent is to be able to distinguish binaries generated from the same +/// source code version but for different target platforms or using different +/// build environments. +/// +#if defined(DOXYGEN) && !defined(POV_BUILD_INFO) + // Work around doxygen being unable to document undefined macros. + #define POV_BUILD_INFO (undefined) + #undef POV_BUILD_INFO +#endif + +/// @def POV_RAY_BUILD_ID +/// Unique build identifier string. +/// +/// This optional macro should be set to a different string each time the build +/// process is run, for example by setting it to a timestamp or the value of a +/// counter automatically incremented before each build. +/// +/// @note +/// If defined, this macro must evaluate to an ASCII string containing only +/// alphanumeric characters or dots. +/// +/// The content of this macro will effectively be appended to the +/// @ref POV_BUILD_INFO, separated by a `.` character. +/// +/// The intent is to be able to distinguish binaries generated from the same +/// source code version for different target platforms and using similar build +/// environments, but with potential minute differences that may or may not +/// cause differences in the binaries. +/// +/// @note +/// This macro should never be defined in any source code, but rather +/// injected via other means as part of the build process, e.g. via a +/// compiler option (`-DPOV_RAY_BUILD_ID=...` in gcc). +/// +#if defined(DOXYGEN) && !defined(POV_RAY_BUILD_ID) + // Work around doxygen being unable to document undefined macros. + #define POV_RAY_BUILD_ID (undefined) + #undef POV_RAY_BUILD_ID +#endif /// @def BUILT_BY /// Specifies the person or organization responsible for this build. -/// @attention Please set this to your real name, and/or include a working email or website address to contact you. +/// +/// @attention +/// Please set this to your real name, and/or include a working email or +/// website address to contact you. +/// +/// @note +/// It is recommended to avoid editing this macro in the source code, +/// and instead inject the macro via other means. If this is not feasible +/// and you are working in a git workspace, it is recommended to run +/// `git update-index --skip-worktree source/base/build.h` to avoid +/// undesired interference between the repository and your local changes. +/// #ifndef BUILT_BY -#define BUILT_BY "YOUR NAME (YOUR EMAIL)" -#error "Please fill in BUILT_BY, then remove this line" + #define BUILT_BY "YOUR NAME (YOUR EMAIL)" + #error "Please fill in BUILT_BY, then remove this line" #endif /// @} diff --git a/windows/README.md b/windows/README.md index ecebf81ec..f74bfb310 100644 --- a/windows/README.md +++ b/windows/README.md @@ -104,6 +104,12 @@ Build Steps `#error` directive afterwards to proceed with the build. Note that if you do not do this you will get compile errors. + Note: If you are building in a Git local workspace, we recommend you run + `git update-index --skip-workspace source/base/build.h`. This will keep + your changes to the file from being included in a commit, or overwritten + in a pull or reset, while still allowing you to pull non-conflicting + updates to the file). + By default, the GUI project is built, and the Console project is excluded. If you wish to generate a simple console version of POV-Ray, please modify the configuration as needed, edit