Add README for CLI subproject.
This commit is contained in:
Fletcher Nichol
parent
136d89ec26
commit
863ecc255b
150
cli/README.md
Normal file
150
cli/README.md
Normal file
@ -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 <fnichol@nichol.ca>
|
||||
|
||||
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] (<fnichol@nichol.ca>)
|
||||
|
||||
## License
|
||||
|
||||
MIT (see [LICENSE-MIT](https://github.com/fnichol/names/blob/master/LICENSE-MIT))
|
||||
Loading…
Reference in New Issue
Block a user