Add man page
This commit is contained in:
parent
5cce3fc560
commit
9c1485824f
276
mkproj.1
Normal file
276
mkproj.1
Normal file
@ -0,0 +1,276 @@
|
||||
.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
|
||||
.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 "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: "tool", or "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 "+=" 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 "make" as well as a "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
|
||||
(*.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.
|
||||
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.
|
||||
.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 "sudo", or "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.
|
||||
.It make uninstall
|
||||
Remove the files that are installed by the `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.
|
||||
Loading…
x
Reference in New Issue
Block a user