ci: update deployment for doc rearrangement

This fixes CI to handle the new documentation files. We also continue to
do more cleanup. In particular, we devise a nicer way of detecting the
most recent Cargo OUT_DIR by writing a dummy file, and looking for the
most recently modified version of that file.

.gitignore

@@ -6,6 +6,7 @@ target
 /ignore/Cargo.lock
 /termcolor/Cargo.lock
 /wincolor/Cargo.lock
+/deployment
 
 # Snapcraft files
 stage
@@ -13,4 +14,4 @@ prime
 parts
 *.snap
 *.pyc
-ripgrep*_source.tar.bz2
+ripgrep*_source.tar.bz2

.travis.yml

@@ -73,7 +73,7 @@ before_deploy: ci/before_deploy.sh
 deploy:
   provider: releases
   file_glob: true
-  file: deployment/${PROJECT_NAME}-${TRAVIS_TAG}-${TARGET}.*
+  file: deployment/${PROJECT_NAME}-${TRAVIS_TAG}-${TARGET}.tar.gz
   skip_cleanup: true
   on:
     condition: $TRAVIS_RUST_VERSION = nightly

build.rs

@@ -31,6 +31,11 @@ fn main() {
         }
     };
     fs::create_dir_all(&outdir).unwrap();
+
+    let stamp_path = Path::new(&outdir).join("ripgrep-stamp");
+    if let Err(err) = File::create(&stamp_path) {
+        panic!("failed to write {}: {}", stamp_path.display(), err);
+    }
     if let Err(err) = generate_man_page(&outdir) {
         eprintln!("failed to generate man page: {}", err);
     }
@@ -65,6 +70,10 @@ fn generate_man_page<P: AsRef<Path>>(outdir: P) -> io::Result<()> {
         eprintln!("Error from running 'a2x': {}", err);
         return Ok(());
     }
+    // 1. Read asciidoc template.
+    // 2. Interpolate template with auto-generated docs.
+    // 3. Save interpolation to disk.
+    // 4. Use a2x (part of asciidoc) to convert to man page.
     let outdir = outdir.as_ref();
     let cwd = env::current_dir()?;
     let tpl_path = cwd.join("doc").join("rg.1.txt.tpl");

ci/before_deploy.sh

@@ -17,31 +17,39 @@ mk_artifacts() {
 }
 
 mk_tarball() {
+    # When cross-compiling, use the right `strip` tool on the binary.
     local gcc_prefix="$(gcc_prefix)"
-    local td="$(mktemp -d)"
+    # Create a temporary dir that contains our staging area.
+    # $tmpdir/$name is what eventually ends up as the deployed archive.
+    local tmpdir="$(mktemp -d)"
     local name="${PROJECT_NAME}-${TRAVIS_TAG}-${TARGET}"
-    local staging="$td/$name"
-    mkdir -p "$staging/complete"
+    local staging="$tmpdir/$name"
+    mkdir -p "$staging"/{complete,doc}
+    # The deployment directory is where the final archive will reside.
+    # This path is known by the .travis.yml configuration.
     local out_dir="$(pwd)/deployment"
     mkdir -p "$out_dir"
+    # Find the correct (most recent) Cargo "out" directory. The out directory
+    # contains shell completion files and the man page.
+    local cargo_out_dir="$(cargo_out_dir "target/$TARGET")"
 
     # Copy the ripgrep binary and strip it.
-    cp target/$TARGET/release/rg "$staging/rg"
+    cp "target/$TARGET/release/rg" "$staging/rg"
     "${gcc_prefix}strip" "$staging/rg"
-    # Copy the README and licenses.
+    # Copy the licenses and README.
     cp {README.md,UNLICENSE,COPYING,LICENSE-MIT} "$staging/"
+    # Copy documentation and man page.
+    cp {CHANGELOG.md,FAQ.md,GUIDE.md} "$staging/doc/"
+    if command -V a2x 2>&1 > /dev/null; then
+      # The man page should only exist if we have asciidoc installed.
+      cp "$cargo_out_dir/rg.1" "$staging/doc/"
+    fi
     # Copy shell completion files.
-    cp \
-      target/"$TARGET"/release/build/ripgrep-*/out/{rg.bash,rg.fish,_rg.ps1} \
-      "$staging/complete/"
-    cp complete/_rg "$td/$name/complete/"
-    # Copy man page.
-    cp \
-      target/"$TARGET"/release/build/ripgrep-*/out/rg.1 \
-      "$td/$name/"
+    cp "$cargo_out_dir"/{rg.bash,rg.fish,_rg.ps1} "$staging/complete/"
+    cp complete/_rg "$staging/complete/"
 
-    (cd "$td" && tar czf "$out_dir/$name.tar.gz" *)
-    rm -rf "$td"
+    (cd "$tmpdir" && tar czf "$out_dir/$name.tar.gz" "$name")
+    rm -rf "$tmpdir"
 }
 
 main() {

ci/install.sh

@@ -22,6 +22,14 @@ install_targets() {
     fi
 }
 
+install_osx_dependencies() {
+    if ! is_osx; then
+      return
+    fi
+
+    brew install asciidoc
+}
+
 configure_cargo() {
     local prefix=$(gcc_prefix)
     if [ -n "${prefix}" ]; then
@@ -44,6 +52,7 @@ EOF
 }
 
 main() {
+    install_osx_dependencies
     install_rustup
     install_targets
     configure_cargo

ci/script.sh

@@ -11,17 +11,16 @@ main() {
     # output of cargo a little trickier. So just wipe it.
     cargo clean
     # Test a normal debug build.
-    cargo build --target "${TARGET}" --verbose --all
+    cargo build --target "$TARGET" --verbose --all
 
-    # Show the output of build.rs stderr.
+    # Show the output of the most recent build.rs stderr.
     set +x
-    find ./target/"$TARGET"/debug -name stderr | while read stderr; do
-      if [ -s "$stderr" ]; then
-        echo "===== $stderr ====="
-        cat "$stderr"
-        echo "====="
-      fi
-    done
+    stderr="$(find "target/$TARGET/debug" -name stderr -print0 | xargs -0 ls -t | head -n1)"
+    if [ -s "$stderr" ]; then
+      echo "===== $stderr ====="
+      cat "$stderr"
+      echo "====="
+    fi
     set -x
 
     # sanity check the file type
@@ -37,19 +36,16 @@ main() {
     "$(dirname "${0}")/test_complete.sh"
 
     # Check that we've generated man page and other shell completions.
-    find ./target/"$TARGET"/debug/build/ripgrep-* -name 'out' | \
-        while read outdir; do
-          file "$outdir/rg.bash"
-          file "$outdir/rg.fish"
-          file "$outdir/_rg.ps1"
-          # man page requires asciidoc, and we only install it on Linux x86.
-          if is_linux; then
-              file "$outdir/rg.1"
-          fi
-        done
+    outdir="$(cargo_out_dir "target/$TARGET/debug")"
+    file "$outdir/rg.bash"
+    file "$outdir/rg.fish"
+    file "$outdir/_rg.ps1"
+    # N.B. man page isn't generated on ARM cross-compile, but we gave up
+    # long before this anyway.
+    file "$outdir/rg.1"
 
     # Run tests for ripgrep and all sub-crates.
-    cargo test --target "${TARGET}" --verbose --all
+    cargo test --target "$TARGET" --verbose --all
 }
 
 main

ci/utils.sh

@@ -2,6 +2,20 @@
 
 # Various utility functions used through CI.
 
+# Finds Cargo's `OUT_DIR` directory from the most recent build.
+#
+# This requires one parameter corresponding to the target directory
+# to search for the build output.
+cargo_out_dir() {
+    # This works by finding the most recent stamp file, which is produced by
+    # every ripgrep build.
+    target_dir="$1"
+    find "$target_dir" -name ripgrep-stamp -print0 \
+      | xargs -0 ls -t \
+      | head -n1 \
+      | xargs dirname
+}
+
 host() {
     case "$TRAVIS_OS_NAME" in
         linux)
@@ -68,3 +82,10 @@ is_linux() {
         *)     return 1 ;;
     esac
 }
+
+is_osx() {
+    case "$TRAVIS_OS_NAME" in
+        osx) return 0 ;;
+        *)   return 1 ;;
+    esac
+}