Installation, portability, dependencies, and testing
Miller license
Two-clause BSD license
https://github.com/johnkerl/miller/blob/master/LICENSE.txt.
Prebuilt executables
Please see
https://github.com/johnkerl/miller/releases where there are builds for OSX
Yosemite, Linux i686 (statically linked), and Linux x86-64 (dynamically
linked).
Homebrew installation support for OSX is available via
brew update && brew install miller
You may already have
mlr available in your platform’s
package manager on NetBSD, Debian Linux, Ubuntu Xenial and upward, Arch Linux, or perhaps other distributions.
For example, on Debian/Ubuntu, you can try
sudo apt-get install miller
Building from source
From release tarball using autoconfig
Miller allows you the option of using GNU autoconfigure to build portably.
Grateful acknowledgement: Miller’s GNU autoconfig work was done by
the generous and expert efforts of
Thomas
Klausner.
Install the flex package using your system’s package
manager (apt-get, yum install, etc.).
Obtain mlr-i.j.k.tar.gz from https://github.com/johnkerl/miller/tags,
replacing i.j.k with the desired release, e.g. 2.2.1.
tar zxvf mlr-i.j.k.tar.gz
cd mlr-i.j.k
- Various configuration options of your choice, e.g.
./configure
./configure --prefix=/usr/local
./configure --prefix=$HOME/pkgs
./configure CC=clang
./configure --disable-shared (to make a statically linked executable)
./configure 'CFLAGS=-Wall -std=gnu99 -O3'
etc.
make creates the c/mlr executable
make check
make install copies the c/mlr executable to your prefix’s bin subdirectory.
From git clone using autoconfig
Install the following packages using your system’s package manager
(apt-get, yum install, etc.):
automake autoconf libtool flex
git clone https://github.com/johnkerl/miller
cd miller
autoreconf -fiv
Then continue from ./configure as above.
Creating a release tarball
Proceed from git-clone as above.
Then edit the package version at the top of configure.ac as well as c/mlrvers.h.
Then make distcheck.
Without using autoconfig
GNU autoconfig is familiar to many users, and indeed plenty of folks won’t bother to use an open-source
software package which doesn’t have autoconfig support. And this is for good reason: GNU autoconfig allows
us to build software on a wide diversity of platforms. For this reason I’m happy that Miller supports
autoconfig.
But, many others (myself included!) find autoconfig confusing: if it works
without errors, great, but if not, the
./configure && make
output can be exceedingly difficult to decipher. And this also can be a
turn-off for using open-source software: if you can’t figure out the
build errors, you may just keep walking. For this reason I’m happy that
Miller allows you to build without autoconfig. (Of course, if you have any
build errors, feel free to contact me at
kerl.john.r+miller@gmail.com,
— or, better, open an issue with “New Issue” at
https://github.com/johnkerl/miller/issues.)
Steps:
Obtain a release tarball or git clone.
cd into the c subdirectory.
Edit the INSTALLDIR in Makefile.no-autoconfig.
To change the C compiler, edit the CC= lines in
Makefile.no-autoconfig and dsls/Makefile.no-autoconfig.
make -f Makefile.no-autoconfig creates the mlr
executable and runs unit/regression tests (i.e. the equivalent of both
make and make check using autoconfig).
make install copies the mlr executable to your install directory.
The
Makefile.no-autoconfig is simple: little more than
gcc
*.c. Customzing is less automatic than autoconfig, but more transparent.
I expect this makefile to work with few modifications on a large fraction of
modern Linux/BSD-like systems: I’m aware of successful use with
gcc and
clang, on Ubuntu 12.04 LTS, SELinux, Darwin (MacOS
Yosemite), and FreeBSD.
In case of problems
If you have any build errors, feel free to contact me at
kerl.john.r+miller@gmail.com,
— or, better, open an issue with “New Issue” at
https://github.com/johnkerl/miller/issues.
Dependencies
Required external dependencies
These are necessary to produce the
mlr
executable.
gcc, clang, etc. (or presumably other compilers; please
open an issue or send me a pull request if you have information for me about
other 21st-century compilers)
The standard C library
flex
automake, autoconf, and libtool, if you build with autoconfig
Optional external dependencies
This documentation pageset is built using
Poki:
docs here,
source code here.
Note that
http://johnkerl.org/miller/doc/index.html
is nothing more than Miller’s
doc directory served up by a web server.
You’ll need
poki if you modify documents, or if you modify the code in a way that affects the documents
(there are auto-run snippets inserted into the doc).
The best way to discover this is to run
make install as above, then run
poki in Miller’s
doc subdirectory, then run
git diff to see if docs were affected
by the code mod. (If so, commit and push them.)
Internal dependencies
These are included within the
Miller source tree and do not
need to be separately installed (and in fact any separate installation will not be picked up in the Miller build):
Creating a new release: for developers
At present I’m the primary developer so this is just my checklist for making new releases.
In this example I am using version 3.4.0; of course that will change for subsequent revisions.
- Update version found in mlr --version and man mlr:
Edit configure.ac, c/mlrvers.h, and mlr.spec
from 3.3.2-dev to 3.4.0.
make -C c -f Makefile.no-autoconfig installhome &&
make -C doc -f Makefile.no-autoconfig all installhome
Commit and push.
ISP upload so http://johnkerl.org/miller/doc/index.html
will have updated head-docs.
- Create the release tarball and SRPM:
Create the Github release tag:
Write the release notes
Attach the release tarball, SRPM, and binaries
Publish the release
Create the release-specific docs:
Pull the Github-generated source .tgz from Github to ISP
miller-releases directory and unpack and cd into it.
cd into doc subdir. Edit template.html’s titleinbody tag from
Miller to Miller 3.4.0 and poki-build.
ISP upload
Back in the Github repo, edit doc/content-for-release-docs.html to include new release, poki-build,
push/commit, and ISP upload.
Notify:
Social-media updates.
Submit brew pull request; notify any other distros which don’t appear to have autoupdated
since the previous release.
Afterwork:
- Edit configure.ac and c/mlrvers.h to change version from 3.4.0 to
3.4.0-dev.
make -C c -f Makefile.no-autoconfig installhome &&
make -C doc -f Makefile.no-autoconfig all installhome
- Commit and push.