bob/mkproj
1
0
Fork 0
Code Issues 1 Pull Requests Actions Packages Projects Releases Wiki Activity

Add FILES section, fix quoting

Browse Source
This commit is contained in:
Bob Polis 2024-12-27 10:21:21 +01:00
parent 1c2e2fd087
commit d5106f796a
1 changed files with 57 additions and 16 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

73
mkproj.1
View File

@ -89,7 +89,19 @@ are mutually exclusive.
.\" For sections 2, 3, and 9 function return values only. .\" For sections 2, 3, and 9 function return values only.
.\" .Sh ENVIRONMENT .\" .Sh ENVIRONMENT
.\" For sections 1, 6, 7, and 8 only. .\" 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 .Sh EXIT STATUS
.\" For sections 1, 6, and 8 only. .\" For sections 1, 6, and 8 only.
.Nm .Nm
@ -127,7 +139,8 @@ mytool
└── precomp.hpp -> ../../src/precomp.hpp └── precomp.hpp -> ../../src/precomp.hpp
.Ed .Ed
.Pp .Pp
In this example, the project name is "mytool". In this example, the project name is
.Dq mytool .
.Pp .Pp
Description: Description:
.Bl -tag -width Ds .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. Makefile rules, dependent on the type of operating system.
Defined here, so you can use it inside the premake.make. Defined here, so you can use it inside the premake.make.
.It PRODUCT .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. Used by the Makefile to do the right thing for either type of project.
.It MAJOR, MINOR, PATCH .It MAJOR, MINOR, PATCH
Together, they form the version for your project. 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 .It CXXFLAGS
This is where the C++ standard is defined. This is where the C++ standard is defined.
Change if needed for your project. 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. variable will be honored.
.It PRECOMPILE .It PRECOMPILE
The project can generate and use a precompiled header. 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. by default a single function which can return a version string.
.Pp .Pp
TODO describe lib header generation, honoring @exclude TODO describe lib header generation, honoring @exclude
.Ss Simple Project Type .Ss Simple Project Type
The simple project is just a directory with a single source file and a Makefile. 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. 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 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. 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 The Makefile is very simple, can do a
more. .Dq make
as well as a
.Dq make clean ,
but no more.
Possible library dependencies should be added to the Makefile. Possible library dependencies should be added to the Makefile.
.Ss Makefile targets .Ss Makefile targets
.Bl -tag -width Ds .Bl -tag -width Ds
.It make .It make
Use this to compile and link your tool. Use this to compile and link your tool.
When doing this with for the first time, or after doing a "make dist-clean", a When doing this with for the first time, or after doing a
"build" subdirectory will be created. .Dq make dist-clean ,
Inside it, an "obj" subdirectory appears, which will contain all object files 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. (*.o), and all dependency files (*.dep), used by the Makefile.
Also, either a "debug" or "release" subdirectory will appear, depending on the Also, either a
definition of the "DEBUG" environment variable. .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. 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 For convenience, a symlink is created on the top level of your project, pointing
to the executable, if it's a tool. 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 .It make test
This will build and run a test tool from the tests directory. 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 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. Running tests will report successes and failures.
.It make install .It make install
When installing your tool and its man page outside your home directory, prefix 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 .It make clean
This will remove compiled object files and dependency files, but keep the This will remove compiled object files and dependency files, but keep the
previously built tool and precompiled header intact. previously built tool and precompiled header intact.
.It make dist-clean .It make dist-clean
This brings the project directory back to a pristine state, removing everything 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 .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 Please note that no dependency checks are done, so removal could break other
tools or libraries that depend on the removed files. tools or libraries that depend on the removed files.
.El .El