From 863ecc255be4c25d7ef6c17f833afd9d8b53b2d7 Mon Sep 17 00:00:00 2001 From: Fletcher Nichol Date: Mon, 2 Nov 2015 09:24:49 -0700 Subject: [PATCH] Add README for CLI subproject. --- cli/README.md | 150 ++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 150 insertions(+) create mode 100644 cli/README.md diff --git a/cli/README.md b/cli/README.md new file mode 100644 index 0000000..4381f5c --- /dev/null +++ b/cli/README.md @@ -0,0 +1,150 @@ +# names + +Random name generator tool that gives you Heroku or Docker-style names. + +## Usage + +Simple! Run without any parameters, you get a name: + +```sh +> names +selfish-change +``` + +Need more? Tell it how many: + +```sh +> names 10 +rustic-flag +nondescript-crayon +picayune-map +elderly-cough +skinny-jeans +neat-rock +aware-sponge +psychotic-coast +brawny-event +tender-oatmeal +``` + +Not random enough? How about adding a 4-number pad: + +```sh +> names --number 5 +imported-rod-9680 +thin-position-2344 +hysterical-women-5647 +volatile-pen-9210 +diligent-grip-4520 +``` + +If you're ever confused, at least there's help: + +```sh +> names --help +names 0.10.0 + +Author: Fletcher Nichol + +A random name generator with results like `delirious-pail'. + +USAGE: + names [FLAGS] [ARGS] + +FLAGS: + -h, --help Prints help information + -n, --number Adds a random number to the name(s) + -V, --version Prints version information + +ARGS: + amount Number of names to generate (default: 1) +``` + +## Installation + +### GitHub releases + +There are binary builds for Mac OS X (referred to as "Darwin") and Linux (a small, self-contained static binary) available through the project's [GitHub releases](https://github.com/fnichol/names/releases). + +### Docker images + +If Docker is more your speed, there's a speedy teeny tiny image (~1MB) on the Docker hub at [fnichol/names](https://hub.docker.com/r/fnichol/names/). It's pretty easy to get started: + +```sh +> docker run fnichol/names 4 +furtive-polish +modern-business +alive-sun +tremendous-line +``` + +### Building from source + +If you want (or need) to build the CLI from source, the following should not take too long. Note that you'll need a version of Rust (and Cargo which ships with the Rust distributions) before running: + +```sh +> git clone https://github.com/fnichol/names.git +> cd names/cli +> cargo build --release +# test it out +> ./target/release/names +``` + +#### A static binary on Linux? + +This project was used by its author to experiment with producing static binaries on Linux from a Rust project that has no external dependencies. This was done using a special build of Rust that supports the [musl](http://www.musl-libc.org/) libc project, available via the [fnichol/rust:1.4.0-musl](https://hub.docker.com/r/fnichol/rust/) Docker image. Here's an example building the CLI to a static ELF binary on Linux: + +```sh +> git clone https://github.com/fnichol/names.git +> cd names +> docker run --rm -ti -v `pwd`:/src -w /src/cli fnichol/rust:1.4.0-musl cargo build --release --target=x86_64-unknown-linux-musl + +> docker run --rm -ti -v `pwd`:/src fnichol/rust:1.4.0-musl du -h ./cli/target/x86_64-unknown-linux-musl/release/names +1.5M ./cli/target/x86_64-unknown-linux-musl/release/names + +> docker run --rm -ti -v `pwd`:/src fnichol/rust:1.4.0-musl ldd ./cli/target/x86_64-unknown-linux-musl/release/names + not a dynamic executable + +> docker run --rm -ti -v `pwd`:/src fnichol/rust:1.4.0-musl file ./cli/target/x86_64-unknown-linux-musl/release/names +./cli/target/x86_64-unknown-linux-musl/release/names: ELF 64-bit LSB executable, x86-64, version 1 (SYSV), statically linked, BuildID[sha1]=6ad327ca3a5b21c42fa158832d89f6e9b0fc8e73, not stripped +``` + +A variant of this approach is used in the [build_linux.sh](https://github.com/fnichol/names/blob/master/cli/scripts/build_linux.sh) script, which additional strips the binary and produces a Zip archive and SHA 256 checksum: + + +```sh +> git clone https://github.com/fnichol/names.git +> cd names +> ./cli/scripts/build_linux.sh 0.10.0 + +> du -h ./cli/target/x86_64-unknown-linux-musl/release/names +996K ./cli/target/x86_64-unknown-linux-musl/release/names + +> file ./cli/target/x86_64-unknown-linux-musl/release/names +./cli/target/x86_64-unknown-linux-musl/release/names: ELF 64-bit LSB executable, x86-64, version 1 (SYSV), statically linked, stripped + +> du -csh ./cli/target/names*.zip* +396K cli/target/names_0.10.0_linux_x86_64.zip +4.0K cli/target/names_0.10.0_linux_x86_64.zip.sha256 +400K total +``` + +## User feedback + +### Issues + +If you have any problems with or questions about this image, please contact us through a [GitHub issue](https://github.com/fnichol/names/issues). + +### Contributing + +You are invited to contribute new features, fixes, or updates, large or small; we are always thrilled to receive pull requests, and do our best to process them as fast as we can. + +Before you start to code, we recommend discussing your plans through a [GitHub issue](https://github.com/fnichol/names/issues), especially for more ambitious contributions. This gives other contributors a chance to point you in the right direction, give you feedback on your design, and help you find out if someone else is working on the same thing. + +## Authors + +Created and maintained by [Fletcher Nichol][fnichol] () + +## License + +MIT (see [LICENSE-MIT](https://github.com/fnichol/names/blob/master/LICENSE-MIT))