Added a make tarball rule to generate an archive

Also updated the README.md a little: added "manual" and "contributor
notes" sections, expanded the installation section, and a couple minor
other edits.

diff --git a/.gitignore b/.gitignore
index 4f20c93c1f7b1f848d480db0b63f11be164909ce..60b16d573afc5f2b7959d9ba1d7fa78823fdf088 100644 (file)
--- a/.gitignore
+++ b/.gitignore
@@ -1,4 +1,3 @@
-# backup files
 *~
 *.o
 *.a
@@ -9,6 +8,6 @@
 *.sav
 *.profraw
 *.profdata
-tests/formal-analysis/*
+tests/formal-analysis*
 doc/html/*.html
 tests/vectors.h

diff --git a/README.md b/README.md
index d8655fa827e55594a12ef333fe765a1e02afb5e2..06591be231e937c744a0caaeb1322574a23f2c80 100644 (file)
--- a/README.md
+++ b/README.md
@@ -4,13 +4,22 @@ Monocypher
 Monocypher is an easy to use, easy to deploy, auditable crypto library
 inspired by [libsodium][] and [TweetNaCl][], written in portable C.
 
-It means to eat libsodium's lunch.
+It means to eat Libsodium's lunch.
 
 [Official site.](http://loup-vaillant.fr/projects/monocypher/)
 
 [libsodium]: http://libsodium.org
 [TweetNaCl]: http://tweetnacl.cr.yp.to/
 
+Manual
+------
+
+The `doc/man/` folder contains the man pages.  You can install them in
+your system by running `make install-doc`.
+
+There is a html version in `doc/html/`, that you can regenerate by
+executing the `doc/man2html.sh` script (this requires mandoc).
+
 
 Installation
 ------------
@@ -19,23 +28,30 @@ The easiest way to use Monocypher is to include `src/monocypher.h` and
 `src/monocypher.c` directly into your project.  They compile as C99,
 C11, C++98, C++11, C++14, and C++17.
 
-Alternatively, you can run
-
-    $ make
-
-then grab `lib/libmonocypher.a` or `lib/libmonocypher.so`.
-
-If you're running a UNIX system, install Monocypher on your system
-(you need to be root):
+Alternatively, you can run `make`, then grab `lib/libmonocypher.a` or
+`lib/libmonocypher.so`.  If you're running a UNIX system, you can even
+install Monocypher (you need to be root):
 
     $ make install
 
 This will install Monocypher in `/usr/local/` by default. Libraries
 will go to `/usr/local/lib/`, the header in `/usr/local/include/`, and
-the man pages in `/usr/local/share/man/man3`.  If you just want the
-man pages, run this:
+the man pages in `/usr/local/share/man/man3`.  You can change those
+defaults with the `PREFIX` and `DESTDIR` variables thus:
+
+    $ make install PREFIX="/opt"
+
+Once installed, you can use `pkg-config` to compile and link your
+program.  For instance, if you have a one file C project that uses
+Monocypher, you can compile it thus:
+
+    $ gcc -o myProgram myProgram.c        \
+        $(pkg-config monocypher --cflags) \
+        $(pkg-config monocypher --libs)
 
-    $ make install-doc
+The `cflags` line gives the include path for monocypher.h, and the
+`libs` line provides the link path and option required to find
+libmonocypher.a (or libmonocypher.so).
 
 
 ### Known language bindings
@@ -64,8 +80,7 @@ It should display a nice printout of all the tests, all starting with
 "OK".  If you see "FAILURE" anywhere, something has gone very wrong
 somewhere.
 
-*Do not* use Monocypher without running the self contained tests at
-least once.
+*Do not* use Monocypher without running those tests at least once.
 
 
 ### More serious testing
@@ -141,9 +156,32 @@ If you need Ed25519 compatibility, you need to do the following:
 
 - Compile Monocypher.c with option -DED25519_SHA512.
 - Link the final program with a suitable SHA-512 implementation.  You
-  can use the sha512.c and sha512.h files provided in `src/`.
+  can use the `sha512.c` and `sha512.h` files provided in `src/`.
 
 Note that even though the default hash (Blake2b) is not "standard",
 you can still upgrade to faster implementations if you really need to.
 The Donna implementations of ed25519 for instance can use a custom
 hash —one test does just that.
+
+
+Contributor notes
+-----------------
+
+If you just cloned the GitHub repository, you will miss a couple files
+that ship with the tarball releases:
+
+- The `test/vectors.h` header.  Generating it requires libsodium. Go
+  to `test/gen/`, then run `make`.
+
+- The html version of the manual, generated by the `doc/man2html.sh`
+  script.  You will need mandoc.
+
+To generate a tarball, simply type `make tarball`.  By default, it
+will generate `../monocypher-master.tar.gz` (yes, in the parent
+directory).  You can override those defaults thus:
+
+    make tarball TARBALL_VERSION=x.y.z TARBALL_DIR=../my_tarballs
+
+This will create a `../my_tarballs/monocypher-x.y.z.tar.gz`, archive
+that contains a single `monocypher-x.y.z` folder with everything in
+it.

diff --git a/doc/man2html.sh b/doc/man2html.sh
index bf6bf49aff030004e540502c67541d5fa1e0d673..eec53ef5488cd20860810850e054002bf8ea2227 100755 (executable)
--- a/doc/man2html.sh
+++ b/doc/man2html.sh
@@ -1,11 +1,10 @@
 #! /bin/sh
 
-mkdir -p html
+DIR=$(dirname "$0")
 
-for name in $(ls -1 "man/man3/" | sed 's/.3monocypher//' | grep -v "style.css")
+for name in $(ls -1 "$DIR/man/man3/" | sed 's/.3monocypher//')
 do
     mandoc                            \
         -Oman=%N.html,style=style.css \
-        -Thtml man/man3/$name.3monocypher > html/$name.html
+        -Thtml "$DIR/man/man3/$name.3monocypher" > "$DIR/html/$name.html"
 done
-

diff --git a/makefile b/makefile
index 346a5e95cc38c91b532c1d111674f743f319106a..9e2194c349fd22c0f92e44e59cfbd23db4a13b45 100644 (file)
--- a/makefile
+++ b/makefile
@@ -5,10 +5,16 @@ PREFIX=usr/local
 PKGCONFIG=$(DESTDIR)/$(PREFIX)/lib/pkgconfig
 MAN_DIR=$(DESTDIR)/$(PREFIX)/share/man/man3
 
+# override with x.y.z when making a proper tarball
+TARBALL_VERSION=master
+# avoids changing the current directory while we archive it
+TARBALL_DIR=..
+
 .PHONY: all library static-library dynamic-library \
         install install-doc                        \
         check test speed                           \
-        clean uninstall
+        clean uninstall                            \
+        tarball
 
 all    : library
 install: library src/monocypher.h install-doc
@@ -97,3 +103,9 @@ tests/vectors.h:
        @echo "======================================================"
        @echo ""
        return 1
+
+tarball: tests/vectors.h
+       doc/man2html.sh
+       tar -czvf $(TARBALL_DIR)/monocypher-$(TARBALL_VERSION).tar.gz \
+            -X tarball_ignore                                         \
+            --transform='flags=r;s|^.|monocypher-$(TARBALL_VERSION)|' .

diff --git a/tarball_ignore b/tarball_ignore
new file mode 100644 (file)
index 0000000..66e299b
--- /dev/null
+++ b/tarball_ignore
@@ -0,0 +1,14 @@
+*~
+*.o
+*.a
+*.so
+*.out
+*.vec
+*.gch
+*.sav
+*.profraw
+*.profdata
+tests/formal-analysis*
+lib*
+.git*
+tarball_ignore