add README.source

1 files changed, 30 insertions, 0 deletions

diff --git a/debian/README.source b/debian/README.source
new file mode 100644
index 0000000..60b6ac5
--- /dev/null
+++ b/debian/README.source
@@ -0,0 +1,30 @@
+Shared library conversion
+-------------------------
+
+As explained in the unpatched README.md, upstream intends zxcvbn-c to
+be embedded in the source trees of projects that require it.  For the
+purposes of this Debian package, though, it is compiled as a shared
+library.
+
+The word lists, *.txt in the source package, may be either
+  (a) compiled to a file zxcvbn.dict, or
+  (b) included in the object compiled from zxcvbn.c (in our case, in
+      libzxcvbn.so.*).
+This choice is made by means of the USE_DICT_FILE compiler macro.
+
+Contrary to what you might expect, method (a) does not permit swapping
+out zxcvbn.dict for a different file: CRCs for zxcvbn.dict are
+compiled into the object compiled from zxcvbn.c (in our case, in
+libzxcvbn.so.0).
+
+So method (a) is useless when zxcvbn-c is compiled as a shared
+library.  Further, it complicates usage: a library user must call
+ZxcvbnInit() with the path to the immutable zxcvbn.dict, and later
+ZxcvbnUninit().
+
+Given the above facts about option (a), I have opted to use option (b)
+for this Debian package.  USE_DICT_FILE is unset.  Calls to
+ZxcvbnInit() and ZxcvbnUninit() are not required, and README.md has
+been patched accordingly.
+
+ -- Sean Whitton <spwhitton@spwhitton.name>, Sat, 24 Sep 2016 14:08:03 -0700