mkproj/mkproj.1

.Dd December 27, 2024
.Dt mkproj 1
.Os
.Sh NAME
.Nm mkproj
.Nd Create C++ project directory with predefined templates
.\" .Sh LIBRARY
.\" For sections 2, 3, and 9	only.
.\" Not used in OpenBSD.
.Sh SYNOPSIS
.Nm
.Fl v
.Nm
.Op Fl f | Fl l | Fl s
.Oo
.Op Fl d
.Fl g Ar gitroot
.Oc
.Op Fl t Ar tplroot
.Ar project
.Sh DESCRIPTION
The
.Nm
script creates a C++ project directory structure with some predefined
boilerplate files, ready to be built using
.Xr make 1 .
.Nm
can create a directory for a simple project using a single source file; a
general project suitable for many source files; a general project setup as a
standard UNIX filter; and a library project, setup to create a static as well as
a shared library.
.Pp
It will also setup the project for use with
.Xr git 1 ,
and do a first commit for the project's files.
.Pp
The main.cpp source files for the general and filter projects already have code
in place to do complete option handling, for long and short options. It can also
display a version string, containing the
.Xr git 1
commit hash, after you have built the tool at least once.
.Pp
The options are as follows:
.Ss General Options
.Bl -tag -width Ds
.It Fl \-version, v
Print version info and exit.
.It Fl \-gitroot Ar gitroot , Fl g Ar gitroot
Clone a
.Xr git 1
repo from the supplied git URL.
When combined with the
.Fl \-default
or
.Fl d
option, the supplied git URL will be saved into the
.Nm
configuration file.
.It Fl \-gitfav , Fl G
Use the git URL saved earlier to clone a repo from.
.It Fl \-tplroot Ar tplroot , Fl t Ar tplroot
Specify the root directory where the project templates can be found.
This option is useful when you want to use a modified set of files to base your
projects on.
.El
.Ss Project Type Options
.Bl -tag -width Ds
.It Fl \-filter, f
Create a filter project.
.It Fl \-library, l
Create a library project.
.It Fl \-simple, s
Create a simple project.
.El
.Pp
Without any
.Sx Project Type Options ,
A general project for a command line tool with multiple source files will be
created.
.Pp
The
.Sx Project Type Options
are mutually exclusive.
.\" .Sh CONTEXT
.\" For section 9 functions only.
.\" .Sh IMPLEMENTATION NOTES
.\" Not used in OpenBSD.
.\" .Sh RETURN VALUES
.\" For sections 2, 3, and 9 function return values only.
.\" .Sh ENVIRONMENT
.\" For sections 1, 6, 7, and 8 only.
.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
exits 0 on success, and 1 if an error occurs.
.\" .Sh EXAMPLES
.\" .Sh DIAGNOSTICS
.\" For sections 1, 4, 6, 7, 8, and 9 printf/stderr messages only.
.\" .Sh ERRORS
.\" For sections 2, 3, 4, and 9 errno settings only.
.Sh PROJECT DESCRIPTION
The project created by
.Nm
has the following features.
.Ss Without Project Type Options
Without any options, a full-featured project for a tool will be created, with
the following layout:
.Bd -literal
mytool
|-- Makefile
|-- man
|   `-- man1
|       `-- mytool.1
|-- premake.make
|-- src
|   |-- main.cpp
|   |-- precomp.hpp
|   |-- version.cpp
|   `-- version.hpp
`-- tests
    |-- Makefile -> ../Makefile
    |-- postmake.make
    |-- premake.make
    `-- src
        |-- main.cpp
        `-- precomp.hpp -> ../../src/precomp.hpp
.Ed
.Pp
In this example, the project name is
.Dq mytool .
.Pp
Description:
.Bl -tag -width Ds
.It Makefile
This is a universal Makefile, which should not be edited.
All customization should be done in premake.make, and, optionally,
postmake.make.
The idea is that you should be able to replace it, at any time, with a newer
version, without affecting the overall functionality.
See
.Sx Makefile targets
below for more details about what's possible here.
.It man directories
Contains a boilerplate man page, ready to be edited with relevant content.
If the project needs multiple man pages, possibly also for man chapter 3 and/or
5, they can be added here.
The structure will be merged into a man directory hierarchy at install time.
.It premake.make
This file will be included by the Makefile, as a first action.
In it, several important project-related Makefile variables can and will be
defined.
.Bl -tag -width Ds
.It LDLIBS
Initially empty, this is where you can specify library dependencies, like
-lsqlite3, or -lpthread.
.It PROJ
By default, this will evaluate to the project directory's name.
Alter only if you really want another name for the tool you'll build.
Defined here, so you can use it inside the premake.make, should you need to
derive other variables from it.
.It UNAME_S
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:
.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.
Important: this is the single source of truth for the version numbering, and
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
.Dq +=
operator here, so a possibly defined $CXXFLAGS environment
variable will be honored.
.It PRECOMPILE
The project can generate and use a precompiled header.
By default, the precomp.hpp file contains the C++ Standard Library headers, but
you could add more to that file, if you like (for example, other library
headers).
By default, it is switched off.
Set to 1 if you want to switch it on.
.It PLUGINS
If your project supports plugins of any type, define the directory name(s) here.
The Makefile will then automatically build and install plugins as well.
Leave empty if your project does not use any plugins.
.El
.It src directory
Subdirectory for headers and source files.
The file already present can be used to compile and build the tool, providing
some nice features out of the box.
See
.Sx Tool Features
below for more information.
.It tests directory
Subdirectory for unit tests, using the Boost Unit Test Framework.
.El
.Ss Filter Project Type
The filter project has an identical structure as the normal type, but adds some
functionality to make the tool behave as a real UNIX filter.
See
.Sx Tool Features
below for more information.
.Ss Library Project Type
The library project has been set up to produce a static and dynamic library from
your sources.
Its directory structure is almost identical to that of a tool.
The only differences are, that the man page is for man chapter 3, and there is
no main.cpp source file.
.Pp
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
.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
.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
.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
.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
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
.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
.Dq make
invocations.
.It make uninstall
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
.Ss Tool Features, out of the box
TODO describe main.cpp and version.cpp here.
.Sh SEE ALSO
.Xr make 1 ,
.Xr git 1 .
.\" .Xr foobar 1
.\" .Sh STANDARDS
.\" .Sh HISTORY
.Sh AUTHORS
Bob Polis
.\" .Sh CAVEATS
.Sh BUGS
.Nm
does no error checking for using multiple
.Sx Project Type Options
at once.
You are at the mercy of the script which type will be created in that case.
.\" .Sh SECURITY CONSIDERATIONS
.\" Not used in OpenBSD.