From d5106f796a13acfcd3c4a974584d26a1ce6ea417 Mon Sep 17 00:00:00 2001 From: Bob Polis Date: Fri, 27 Dec 2024 10:21:21 +0100 Subject: [PATCH] Add FILES section, fix quoting --- mkproj.1 | 73 +++++++++++++++++++++++++++++++++++++++++++------------- 1 file changed, 57 insertions(+), 16 deletions(-) diff --git a/mkproj.1 b/mkproj.1 index ccce279..5e0ebec 100644 --- a/mkproj.1 +++ b/mkproj.1 @@ -89,7 +89,19 @@ are mutually exclusive. .\" For sections 2, 3, and 9 function return values only. .\" .Sh ENVIRONMENT .\" For sections 1, 6, 7, and 8 only. -.\" .Sh FILES +.Sh FILES +.Bl -tag -width Ds +.It Pa ~/.config/mkprojrc +This file is sourced by the +.Nm +script, and will at least contain the definition for the +.Sq tplroot +variable, and possibly also the definition of the +.Sq gitroot +variable. +Since it is shell syntax, paths should be properly quoted, and comments are +allowed. +.El .Sh EXIT STATUS .\" For sections 1, 6, and 8 only. .Nm @@ -127,7 +139,8 @@ mytool └── precomp.hpp -> ../../src/precomp.hpp .Ed .Pp -In this example, the project name is "mytool". +In this example, the project name is +.Dq mytool . .Pp Description: .Bl -tag -width Ds @@ -163,7 +176,10 @@ Should not be changed; here as a convenience to be able to conditionally define Makefile rules, dependent on the type of operating system. Defined here, so you can use it inside the premake.make. .It PRODUCT -Only two values allowed: "tool", or "lib". +Only two values allowed: +.Dq tool , +or +.Dq lib . Used by the Makefile to do the right thing for either type of project. .It MAJOR, MINOR, PATCH Together, they form the version for your project. @@ -172,7 +188,9 @@ will be used in the Makefile as well as in the preinstalled sources. .It CXXFLAGS This is where the C++ standard is defined. Change if needed for your project. -Note the "+=" operator here, so a possibly defined $CXXFLAGS environment +Note the +.Dq += +operator here, so a possibly defined $CXXFLAGS environment variable will be honored. .It PRECOMPILE The project can generate and use a precompiled header. @@ -213,29 +231,44 @@ When building the library, a static and dynamic library are produced, containing by default a single function which can return a version string. .Pp TODO describe lib header generation, honoring @exclude - .Ss Simple Project Type The simple project is just a directory with a single source file and a Makefile. The idea is that you use this for simple, quick proof-of-concept tools. Here, the source file has the same name as the project, and is almost empty, so nothing is in the way to make it do what you want. -The Makefile is very simple, can do a "make" as well as a "make clean", but no -more. +The Makefile is very simple, can do a +.Dq make +as well as a +.Dq make clean , +but no more. Possible library dependencies should be added to the Makefile. .Ss Makefile targets .Bl -tag -width Ds .It make Use this to compile and link your tool. -When doing this with for the first time, or after doing a "make dist-clean", a -"build" subdirectory will be created. -Inside it, an "obj" subdirectory appears, which will contain all object files +When doing this with for the first time, or after doing a +.Dq make dist-clean , +a +.Dq build +subdirectory will be created. +Inside it, an +.Dq obj +subdirectory appears, which will contain all object files (*.o), and all dependency files (*.dep), used by the Makefile. -Also, either a "debug" or "release" subdirectory will appear, depending on the -definition of the "DEBUG" environment variable. +Also, either a +.Dq debug +or +.Dq release +subdirectory will appear, depending on the +definition of the +.Ev DEBUG +environment variable. This is the place where your tool or libraries will appear. For convenience, a symlink is created on the top level of your project, pointing to the executable, if it's a tool. -That way, you can simply do "./mytool" to run it. +That way, you can simply do +.Ql ./mytool +to run it. .It make test This will build and run a test tool from the tests directory. You are expected to add your tests to the tests/src/main.cpp file, using @@ -243,15 +276,23 @@ assertions from the Boost Unit Test Framework. Running tests will report successes and failures. .It make install When installing your tool and its man page outside your home directory, prefix -with "sudo", or "doas", depending on your system. +with +.Dq sudo , +or +.Dq doas , +depending on your system. .It make clean This will remove compiled object files and dependency files, but keep the previously built tool and precompiled header intact. .It make dist-clean This brings the project directory back to a pristine state, removing everything -that is generated using the various "make" invocations. +that is generated using the various +.Dq make +invocations. .It make uninstall -Remove the files that are installed by the `make install' invocation. +Remove the files that are installed by the +.Sq make install +invocation. Please note that no dependency checks are done, so removal could break other tools or libraries that depend on the removed files. .El