1Since mk-configure-0.34.0 special mk files
2(mkc_imp.cc_${CC_TYPE}-${CC_VERSION}.mk for C compiler and
3mkc_imp.cxx_${CXX_TYPE}-${CXX_VERSION}.mk for C++ compiler) are
4created and installed, there some compiler settings are stored. That
5is, mk-configure learns some important things about compilers at build
6time and uses this information at the time of mk-configure-based
7project build. By default if required mkc_imp.cc_XXX or
8mkc_imp.cxx_XXX file is absent, mk-configure fails, because it doesn't
9know how to work with unknown compiler. This may lead to package
10(based on mk-configure) failures, when system-wide compiler is updated
11but mk-configure package is not. On some Linux distributions (e.g.,
12Debian unstable), where compiler is updated regularly, such failures
13is a typical situation. In order to fix this, I'd recommend to build
14mk-configure-based packages like the following:
15
16 export HOME=/path/to/temporary/home
17 mkdir -p "$HOME"
18 export MKCOMPILERSETTINGS=yes
19 ... other settings, e.g., PREFIX, SYSCONFDIR etc.
20 mkcmake all install
21
22As you can see, MKCOMPILERSETTINGS is set to "yes". This means that
23appropriate mkc_imp.cc_XXX or mkc_imp.cxx_XXX files are created in
24temporary HOME directory automatically, if system-wide mk files
25correspond to a different compiler. Note that MKCOMPILERSETTINGS
26variable appeared in mk-configure-0.36.0.
27
README.md
1[toc]
2
3Installation
4------------
5
6See [doc/INSTALL.md](https://github.com/cheusov/mk-configure/blob/master/doc/INSTALL.md)
7file for build and installation instructions.
8
9What is mk-configure?
10---------------------
11
12**mk-configure** is a lightweight replacement for *GNU autotools*,
13written in and for bmake (portable version of **NetBSD** make) and
14**UNIX** tools (_shell_, _awk_ etc.). **FreeBSD** and **OpenBSD** make
15are not good. They are incompatible with _NetBSD bmake_. _GNU
16make_ is not good too.
17
18**mk-configure** provides a number of include files (.mk files) written in
19bmake and a number of standalone programs that should be installed to
20user's host for building a software.
21
22**mk-configure** features:
23
24 - An easy way for building standalone executables, static and shared
25 libraries written in _C_, _C++_ and _Objective
26 C_; _.cat_ and _.html_ files from man pages; _.info_ pages from _texinfo_
27 sources etc. _LEX_, _YACC_ are also supported. Support for other
28 languages are planned.
29
30 - Installing and uninstalling executables, libraries, scripts,
31 documentation files and others. DESTDIR support is also provided.
32
33 - Integrated autoconf-like support for finding #include files,
34 libraries and function implementation, function definitions,
35 defines, types, struct members etc.
36
37 - A number of built-in checks for, e.g., system endianness, _GNU bison_
38 or _GNU flex_ programs and many others.
39
40 - Automatic dependency analysis built-in for C and C++.
41
42 - Extensibility by writing bmake include files.
43
44 - Support for regression tests (see *mkc.minitest.mk* for the sample).
45
46 - mk-configure is small and easy. It is definitely much easier for
47 use than _GNU autotools_, many people think that it is also easier
48 than other competing projects like _CMake_, _scons_ and others.
49
50Project goals
51-------------
52
53 - No code generation! Library approach is used instead. Instead of
54 generating tons of unreadable blobs **mk-configure** uses bmake include
55 files (bmake's library) and external executables to make its job.
56 Developers should distribute source code only, not blobs.
57
58 - Single top level command for building a program (**mkcmake**).
59 Instead of running and learning
60 autoconf/automake/aclocal/autoreconf/config.status/autoheader and
61 many other tools, and the way they interact with each other, you
62 should learn only ONE tool, bmake (**mkcmake** is a trivial wrapper
63 over bmake).
64
65 - No bloat. At this time **mk-configure** consists of far less than 10000
66 lines of code (excluding examples and regression tests). Compare
67 this number with autotools sources and you'll see a difference.
68
69 - Simplicity for both developers and users. The only file developers
70 should be aware of during development is 'Makefile'. Users just
71 run
72
73 $ mkcmake help
74 $ env <variables> mkcmake all <options>
75
76 to build a software. The
77 same for developers -- for building a software, just run **mkcmake**.
78
79 - Portability. At the moment the following systems and compilers are
80 supported:
81
82 - **NetBSD**. Tested on NetBSD-5.0/x86 and NetBSD-2.0/alpha and later
83 versions with gcc, pcc and clang.
84
85 - **FreeBSD**. Tested on FreeBSD-6.2/x86, 7.1/spark64, 7.1/x86 and
86 later versions with gcc and clang.
87
88 - **OpenBSD**. Tested on OpenBSD-3.8/x86, 4.5/x86 and later versions
89 with gcc.
90
91 - **DragonFlyBSD**. Tested on DragonFly-2.4.1-RELEASE/x86 and later
92 versions with gcc.
93
94 - **MirOS BSD**. Tested on MirBSD-10/x86 and later versions with gcc.
95
96 - **Linux**. Tested on Linux/{x86,x86-64,ppc,armv7,aarch64} with glibc/musl, gcc,
97 icc and SunStudio compilers.
98
99 - **Solaris**. Tested on Solaris-{10,11}/{spark64,x86}
100 with SunC-5.11, SunC-5.15 and gcc.
101
102 - **Darwin** (macOS). Tested on Darwin-8.11.0/ppc (MacOS-X Tiger)
103 and later version with native gcc and clang.
104
105 - **Interix**. Tested on Interix-3.5/x86 with gcc.
106
107 - **QNX**. Tested on QNX-6.3/x86 with gcc.
108
109 - **OSF1**. Tested on Tru64-5.1/alpha with gcc and DEC C compiler.
110
111 - **HP-UX**. Tested on HP-UX-11.0/hppa with gcc.
112
113 - Partial support for **AIX** and their native
114 compilers. Support is not complete because I have no access to
115 "big iron" :-( .
116
117 If you don't see your favorite system/compiler here and want to
118 help me to improve **mk-configure**, feel free to contact me.
119
120 - Declarative approach in writing Makefiles. Instead of specifying
121 how to build your software, you should specify source files,
122 files to build and (optionally) build options, e.g. LDCOMPILER=yes
123 meaning that ${CC} or ${CXX} compiler should be used as a linker
124 instead of ${LD}. Small/medium size projects may have no rules in
125 Makefiles at all. Most useful things are already implemented in
126 **mk-configure** Mk files including targets
127 "all", "install", "uninstall" as well as support for building the shared
128 libraries, installation to ${DESTDIR} etc. Usually, Makefile contain
129 only variable assignments, .include-s and .if/.for directives.
130
131 - No heavy dependencies like Python or Perl.
132
133How to use mk-configure?
134------------------------
135
136Developers:
137 - Install **mk-configure** to your system.
138 - Run **mkcmake** or **mkcmake all** for building your program.
139 You don't need autoconf/autoheader/automake/aclocal/config.guess/
140 /autoreconf/config.status/config.sub and blah-blah-blah
141
142Users and software packagers:
143 - Install **mk-configure** to your system.
144 - Run **mkcmake** for building a software and pass to it
145 the building options, e.g.
146
147 $ export CC=pcc
148 $ export CFLAGS='-O0 -g'
149 $ export PREFIX=$HOME/local
150 $ mkcmake all install
151
152What mk-configure consists of?
153------------------------------
154
155- *mkc.{files,lib,prog,subprj,subdir}.mk* files.
156
157 These include files are responsible for building, installing and
158 uninstalling applications, static and shared libraries, scripts,
159 text files, man and info pages, hard and soft links etc...
160
161 NOTE FOR *BSD USERS: unlike well known Mk files from \*BSD
162 systems *mkc.\*.mk* files provide the following features (this list
163 is not complete, see *mk-configure.7* for details).
164
165 + PREFIX, BINDIR, MANDIR etc. variables default to directories
166 under /usr/local. By default the same variables in *bsd.\*.mk*
167 files are set to directories under /usr. The reason is that they
168 are used mainly for maintaining \*BSD's own code
169 while **mk-configure** is targeted to all UNIX-like systems, not only \*BSD.
170
171 + BINOWN, BINGRP, MANOWN etc. variables are set to 'id -u' and
172 'id -g' if **mkcmake(1)** is run under an unprivileged user.
173 By default *bsd.\*.mk* use root:wheel by default.
174
175 + A target 'install' installs the target directories if needed.
176
177 + A target 'uninstall' removes all installed files from
178 destination directories. *bsd.\*.mk* files do not provide
179 this functionality.
180
181 + A target 'test' of *mkc.subdir.mk* (by default) runs a "test"
182 target for each subdirectory listed in SUBDIR. Other *mkc.\*.mk*
183 files provide "test" target too but does nothing by default.
184 If you want to test your application, define your own "test"
185 target in subprojects's Makefile.
186
187 + "cleandir" target removes all temporary
188 files and **mk-configure**'s cache files.
189
190 + support for texinfo/info files. There is no need to .include
191 a special include files such as _bsd.info.mk_ file.
192
193 + *mkc.subprj.mk* is a powerful replacement
194 for traditional _bsd.subdir.mk_.
195
196 + Tons of other additions and improvements.
197
198- _mkc.intexts.mk_. Given a list of files in INFILES or INSCRIPTS *mkc.intexts.mk*
199 generates them from appropriate *.in file replacing @prefix@,
200 @sysconfdir@, @libdir@, @bindir@, @sbindir@, @datadir@ etc. with
201 real ${PREFIX}, ${SYSCONFDIR} etc. See examples/ subdirectory for
202 the samples.
203
204- *mkc.configure.mk*. It is a replacement for _GNU autoconf_. Its
205 functionality is large enough to describe here. In short, it allows
206 to check for presence of header files, function or variable
207 declarations, presence of function in a particular library, defines,
208 sizeof of data types and other useful things. Read the documentation
209 in *mk-configure.7* and see examples/ subdirectory for the samples of
210 use.
211
212- Standalone full-functional
213 **mkc\_check\_{funclib,header,sizeof,decl,prog,custom,compiler}** and
214 other programs that can be used without **mkcmake** and without _mkc.*.mk_
215 files. Read appropriate man pages.
216
217- This list is not complete. Have a look at *mk-configure.7* for details.
218
219Documentation
220-------------
221
222 - Subdirectory presentation/ contains a PDF file which demonstrates
223 some basic ideas and samples of use.
224
225 - In subdirectory examples/ you may find a lot of examples.
226
227 - Documentation for mk include files is in *mk-configure.7*).
228
229 - [doc/NOTES](https://github.com/cheusov/mk-configure/blob/master/doc/NOTES)
230 contains a number of useful recipes.
231
232 - Read the [doc/FAQ](https://github.com/cheusov/mk-configure/blob/master/doc/FAQ)
233 document. It may be helpful.
234
235 - Most of my [personal projects](https://github.com/cheusov) use **mk-configure**.
236 You can use them for learning.
237
238 - Plans are here [doc/TODO](https://github.com/cheusov/mk-configure/blob/master/doc/TODO).
239
240mk-configure binary packages
241----------------------------
242
243Binary packages for **mk-configure** are available in the following systems (this list may be incomplete):
244
245 * NetBSD pkgsrc (devel/mk-configure).
246
247 * FreeBSD ports (devel/mk-configure)
248
249 * Debian/Ubuntu Linux
250
251 * AltLinux
252
253 * Arch Linux
254
255 * OpenSuSE Linux
256
257Feedback
258--------
259
260Please register bug reports and pull requests here
261[mk-configure home](http://github.com/cheusov/mk-configure)
262
263Feel free to notify me about spelling errors in the documentation.
264
265-------------------------------------------------------------------------
266