From: Loup Vaillant Date: Wed, 4 Oct 2017 21:28:53 +0000 (+0200) Subject: Added a make tarball rule to generate an archive X-Git-Url: https://git.codecow.com/?a=commitdiff_plain;h=9ee8eb6f6e3e21b11a3dc38e745cbe79686e168b;p=Monocypher.git 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 4f20c93..60b16d5 100644 --- 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 d8655fa..06591be 100644 --- 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 bf6bf49..eec53ef 100755 --- 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 346a5e9..9e2194c 100644 --- 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 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