digest-kangarootwelve 0.3.2 → 0.4.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: fe63a409aef358036b2c298c06de28e0a6916bfa283f02303b58d9fcab607af1
-  data.tar.gz: d2ab330b5ede162c6bbea6616b451608927535ce01ecd95dc532c415dc1bfa00
+  metadata.gz: 5c8b25102cf3f6a925000487653a245a6f153de17a12319ebfd1c6c25549daf6
+  data.tar.gz: 12d05f0e8b6927105aebc1feffb5bb68482f9235fa6afcee2265b4eeba54cdb2
 SHA512:
-  metadata.gz: 95c04bb572011f47a793f5c25529c99f742fb7d2b9c074c79f639b09dd259ea17ce3faa3485115e95049f5bf07e36a44ae8c5756cb00ae0befbc65d99fa572b9
-  data.tar.gz: f5a553b015a3fc000a401eb7cd6679dba463373e046d45bf60470ed60a9484faf1ca72e1ba80afd21900eac69e461b5f92539a130548e514032a0b74ee5103af
+  metadata.gz: f3e2047eb8379800ba6fe5bd2b4af801ea3a64e1d62581dd9f0267e2d0ee87c5e963e1e2874d5b57f99c4e5f007fb07fe8749ce3ea452482ea076964e213af6f
+  data.tar.gz: 9af6b30aef3113ad635cb870628adce507728d684de587d54fb0c14a96d9e0ee1aa984a4cdf32fd18fa50ed1bd1df2711e166c65c656ebc1391963d36b44685f

data/LICENSE

@@ -1,4 +1,4 @@
-Copyright (c) 2017 konsolebox
+Copyright (c) 2022 konsolebox
 
 MIT License
 

data/LICENSE.XKCP

@@ -0,0 +1,9 @@
+# Under which license is the XKCP distributed?
+
+Most of the source and header files in the XKCP are released to the **public domain** and associated to the [CC0](http://creativecommons.org/publicdomain/zero/1.0/) deed. The exceptions are the following:
+
+* [`lib/common/brg_endian.h`](lib/common/brg_endian.h) is copyrighted by Brian Gladman and comes with a BSD 3-clause license;
+* [`tests/UnitTests/genKAT.c`](tests/UnitTests/genKAT.c) is based on [SHA-3 contest's code by Larry Bassham, NIST](http://csrc.nist.gov/groups/ST/hash/sha-3/documents/KAT1.zip), which he licensed under a BSD 3-clause license;
+* [`tests/UnitTests/timing.h`](tests/UnitTests/timing.h) is adapted from Google Benchmark and is licensed under the Apache License, Version 2.0;
+* [`KeccakP-1600-AVX2.s`](lib/low/KeccakP-1600/AVX2/KeccakP-1600-AVX2.s) is licensed under the [CRYPTOGAMS license](http://www.openssl.org/~appro/cryptogams/) (BSD-like);
+* [`support/Kernel-PMU/enable_arm_pmu.c`](support/Kernel-PMU/enable_arm_pmu.c) is licensed under the GNU General Public License by Bruno Pairault.

data/README.md

@@ -1,63 +1,116 @@
 # digest-kangarootwelve
 
-The digest-kangarootwelve gem is an implementation of KangarooTwelve for Ruby
-that works on top of `Digest::Base`.
+This gem is an implementation of KangarooTwelve for Ruby that works on top of
+the `Digest::Base` class.
 
-It allows hashing with different digest lengths and different customization
-strings.
+It can be configured to produce outputs with different digest lengths, and can
+be initilized with different customization strings.
 
-See http://kangarootwelve.org/ to know more about the hashing algorithm.
+To know more about the KangarooTwelve algorithm, visit
+https://keccak.team/kangarootwelve.html.
 
-The core implementation was extracted/generated from the KCP
-(https://github.com/gvanas/KeccakCodePackage).
+The core implementation of KangarooTwelve is part of the
+[XKCP](https://github.com/XKCP/XKCP) project.
 
-KCP provides implementations on many target platforms.  This gem used to only
-have the `compact` implementation, but it now has adopted all of them.
+XKCP provides multiple targets for different architecture-dependent builds.
 
-The available implementation targets are `armv6m`, `armv7a`, `armv7m`, `armv8a`,
-`asmx86-64`, `asmx86-64shld`, `avr8`, `bulldozer`, `compact`, `generic32`,
-`generic32lc`, `generic64`, `generic64lc`, `haswell`, `nehalem`, `reference`,
-`reference32bits`, `sandybridge`, and `skylakex`, with `compact`  being the
-default.
+This gem can be configured to compile differently based on the target specified.
 
-Instructions on how to select a target is written below.
+The current target implementations are `armv6`, `armv6m`, `armv7a`, `armv7m`,
+`armv8a`, `avr8`, `avx`, `avx2`, `avx2noasm`, `avx512`, `avx512noasm`,
+`compact`, `generic32`, `generic32lc`, `generic64`, `generic64lc`, `reference`,
+`reference32bits`, `ssse3`, and `xop`, with `compact` being the default target.
+
+Details on what architectures these targets support are provided in the
+[README.markdown](https://github.com/XKCP/XKCP/blob/master/README.markdown) file
+of XKCP.
 
 ## Installation
 
-Add this line to the application's Gemfile:
+To use the gem in an application, add the following line to the application's
+Gemfile:
 
     gem 'digest-kangarootwelve'
 
 And then execute:
 
-    $ bundle
+    bundle
+
+The gem can also be installed manually using the `gem` command:
+
+    gem install digest-kangarootwelve
 
-It can also be installed manually with:
+To build and install the gem against a different platform target, use a
+`--with-target` option that follows a `--`.  Example:
 
-    $ gem install digest-kangarootwelve
+    gem install digest-kangarootwelve -- --with-target=avx
 
-To install with a different platform target, use `--with-target`.  Example:
+Targets may also need `CFLAGS` specified.  Please see the
+[Build failures](#build-failures) section.
 
-    $ gem install digest-kangarootwelve -- --with-target=sandybridge
+It's also a good idea to test the gem before actively using it, especially when
+using a not so commonly used target.  Here's one way to test it:
 
-It's a good idea to test the gem when using a different target platform other
-than default as some platforms are not yet tested, and behavior of optimized
-code can vary on different machines or compilers.  This can be done by running
-the following command.  Replace VERSION with the installed gem's version.
+    cd GEM_DIR/gems/digest-kangarootwelve-VERSION
+    bundle
+    rake test
 
-    $ ( cd "$(ruby -e 'puts Gem.dir')"/gems/digest-kangarootwelve-VERSION && bundle && rake test )
+To know the right value of GEM_DIR, try running `gem info digest-kangarootwelve`.
 
-The library can also be installed in Gentoo system-wide using 'layman':
+## Installing in Gentoo
 
-    # Fetch remote list of overlays, and add 'konsolebox' overlay
+The library can also be globally installed in Gentoo using `layman`:
+
+    # Fetch remote list of overlays, and add 'konsolebox' overlay.
     layman -f && layman -a konsolebox
 
-    # Unmask unstable keyword
-    echo 'dev-ruby/digest-kangarootwelve' > /etc/portage/package.keywords/dev-ruby.digest-kangarootwelve
+    # Unmask unstable keyword.
+    echo 'dev-ruby/digest-kangarootwelve' > /etc/portage/package.accept_keywords/dev-ruby.digest-kangarootwelve
 
-    # Merge package
+    # Merge package.
     emerge dev-ruby/digest-kangarootwelve
 
+## Testing from source
+
+The gem can also be tested from source using the following commands:
+
+    # Clone this repo.
+    git clone https://github.com/konsolebox/digest-kangarootwelve-ruby.git -b master
+
+    # Change to directory.
+    cd digest-kangarootwelve-ruby
+
+    # Optionally checkout a tagged version.
+    git checkout v0.4.0
+
+    # Run bundle
+    bundle
+
+    # Finally run `rake` to compile the extension and test the gem.
+    rake
+
+    # A different target can also be specified.  Example:
+    rake clean clobber && rake -- --with-target=avx
+
+## Build failures
+
+Targets like AVX2 may fail to build unless an explicit `CFLAGS` with proper
+architecture-related options is specified.
+
+Specifying a `CFLAGS` can be done by using the `--with-cflags` option.  For example:
+
+    rake -- --with-target=avx2 --with-cflags="-march=native"
+
+    gem install digest-kangarootwelve -- --with-target=avx2 --with-cflags="-march=native"
+
+    bundle config build.digest-kangarootwelve --with-target=avx2 --with-cflags="-march=native"
+
+Compact (the default target) and AVX targets have been tested to not need a
+`CFLAGS` to compile and work.
+
+Please note that this gem has not been tested to work with cross-compilations,
+so please test the resulting runtime thoroughly.
+
 ## Example Usage
 
     Digest::KangarooTwelve[32].digest("abc")
@@ -113,6 +166,5 @@ https://rubygems.org/gems/digest-kangarootwelve
 4. Push to the branch (`git push origin my-new-feature`).
 5. Create a new Pull Request.
 
-[![Build Status](https://travis-ci.org/konsolebox/digest-kangarootwelve-ruby.svg?branch=master)](https://travis-ci.org/konsolebox/digest-kangarootwelve-ruby)
-[![Build Status](https://ci.appveyor.com/api/projects/status/bwedifhi4wa5wik7?svg=true)](https://ci.appveyor.com/project/konsolebox/digest-kangarootwelve-ruby)
 [![Build Status](https://github.com/konsolebox/digest-kangarootwelve-ruby/actions/workflows/ruby.yml/badge.svg)](https://github.com/konsolebox/digest-kangarootwelve-ruby/actions/workflows/ruby.yml)
+[![Build Status](https://ci.appveyor.com/api/projects/status/bwedifhi4wa5wik7?svg=true)](https://ci.appveyor.com/project/konsolebox/digest-kangarootwelve-ruby)

data/Rakefile

@@ -1,18 +1,91 @@
-# build, clean, clobber, install, install:local, release[remote]
+# build, clean, clobber, release[remote]
+
 require 'bundler/gem_tasks'
 
-# clean, clobber, compile, compile:digest/kangarootwelve
+# clean
+
+CLEAN.include "ext/digest/kangarootwelve/Makefile"
+CLEAN.include "ext/digest/kangarootwelve/**/*.o"
+CLEAN.include "ext/digest/kangarootwelve/**/*.so"
+
+# clobber
+
+if File.exist?(".git")
+  CLOBBER.include "LICENSE.XKCP"
+  CLOBBER.include "ext/digest/kangarootwelve/XKCP"
+  CLOBBER.include "ext/digest/kangarootwelve/targets"
+end
+
+# initialize_xkcp
+
+desc "Initialize and update XKCP submodule"
+task :initialize_xkcp => ".git" do |t|
+  puts "Initializing and updating XKCP submodule"
+  system "git submodule init && git submodule update -f"
+end
+
+file "XKCP/Makefile.build" => :initialize_xkcp
+file "XKCP/README.markdown" => :initialize_xkcp
+
+# import_xkcp_license
+
+task :import_xkcp_license do
+  Rake::Task["XKCP/README.markdown"].invoke
+  puts "Extracting XKCP license from \"XKCP/README.markdown\" and saving it to \"LICENSE.XKCP\"."
+  license = File.binread("XKCP/README.markdown")
+                .scan(/# Under which license is the XKCP.*?(?=^#)/m).first
+  raise "No license extracted" unless license
+  File.binwrite("LICENSE.XKCP", license.strip + "\n")
+end.instance_eval do
+  def needed?
+    !File.exist?("LICENSE.XKCP") || File.exist?("XKCP/README.markdown") &&
+        File.mtime("LICENSE.XKCP") < File.mtime("XKCP/README.markdown")
+  end
+end
+
+# import_xkcp_files_lazy
+
+task :import_xkcp_files_lazy do
+  Rake::Task[:import_xkcp_files].invoke
+end.instance_eval do
+  def needed?
+    %w[XKCP targets].any?{ |dir| !File.exist?("ext/digest/kangarootwelve/#{dir}") }
+  end
+end
+
+# build
+
+Rake::Task[:build].prerequisites.unshift :import_xkcp_files
+Rake::Task[:build].prerequisites.unshift :import_xkcp_license
+Rake::Task[:build].prerequisites.unshift :clobber
+
+# compile, compile:digest/kangarootwelve
+
 require 'rake/extensiontask'
 Rake::ExtensionTask.new('digest/kangarootwelve', Bundler::GemHelper.gemspec)
+Rake::Task[:compile].prerequisites.unshift :import_xkcp_files_lazy
+
+# compile_lazy
+
+task :compile_lazy do
+  Rake::Task[:compile].invoke
+end.instance_eval do
+  def needed?
+    !File.exist?("lib/digest/kangarootwelve.so")
+  end
+end
 
 # test
+
 require 'rake/testtask'
-Rake::TestTask.new(:test) do |t|
+
+Rake::TestTask.new(:test => :compile_lazy) do |t|
   t.test_files = FileList['test/test.rb']
   t.verbose = true
 end
 
-# Set 'test' as default task.
+# default
+
 task :default => [:compile, :test]
 
 # Run `rake --tasks` or `rake --tasks --all` for a list of tasks.