diff options
| -rw-r--r-- | .gitignore | 2 | ||||
| -rw-r--r-- | Makefile | 60 | ||||
| -rw-r--r-- | README.txt | 38 | ||||
| -rw-r--r-- | configs/exuberantbovines.xml (renamed from extra/exuberantbovines.xml) | 0 | ||||
| -rw-r--r-- | doc/exuberantbovines.6.md | 77 |
5 files changed, 153 insertions, 24 deletions
@@ -1,4 +1,6 @@ target/ +doc/*.6 +doc/*.6.gz *.o *.a @@ -4,27 +4,32 @@ # This Makefile is self-documenting (via the 'help' target) # see: http://marmelab.com/blog/2016/02/29/auto-documented-makefile.html -CARGO = cargo -CARGO_OPTS = -PREFIX=/usr - HACKS=exuberantbovines + +CARGO ?= cargo +CARGO_OPTS ?= +PREFIX ?= /usr +PANDOC ?= pandoc +PANDOCFLAGS ?= +MANSECTION = 6 +MANPAGE.md = $(PANDOC) --standalone $(PANDOCFLAGS) --to man +MANPAGES = $(foreach HACK, $(HACKS), doc/$(HACK).$(MANSECTION)) +MANPAGEZ = $(foreach HACK, $(HACKS), doc/$(HACK).$(MANSECTION).gz) + INSTALL_BIN=$(PREFIX)/lib/xscreensaver INSTALL_CONFIG=$(PREFIX)/share/xscreensaver/config -INSTALL_MAN=$(PREFIX)/share/man +INSTALL_MAN=$(PREFIX)/share/man/man$(MANSECTION) -all: ## Alias for build - $(MAKE) build - $(MAKE) doc +all: build doc ## Alias for build build: ## Compiles the default target - $(CARGO) $(CARGO_OPTS) build + @$(CARGO) $(CARGO_OPTS) build build-debug: ## Compiles for 'debug' target - $(CARGO) $(CARGO_OPTS) build --debug + @$(CARGO) $(CARGO_OPTS) build --debug build-release: ## Compiles for 'release' target - $(CARGO) $(CARGO_OPTS) build --release + @$(CARGO) $(CARGO_OPTS) build --release install: build-release doc-release ## Installs everything! @echo "Installing under $(PREFIX)..." @@ -32,8 +37,12 @@ install: build-release doc-release ## Installs everything! sudo mkdir -p $(PREFIX)/share/xscreensaver/config @for PROG in $(HACKS); do \ sudo install -m 0755 target/release/$$PROG $(INSTALL_BIN); \ - sudo install -m 0644 extra/$$PROG.xml $(INSTALL_CONFIG); \ + sudo install -m 0644 configs/$$PROG.xml $(INSTALL_CONFIG); \ + sudo install -m 0644 doc/$$PROG.$(MANSECTION).gz $(INSTALL_MAN); \ done + @echo "Updating mandb (this takes a few seconds)..." + @sudo mandb -q + @echo "" @echo "IMPORTANT: For the hacks to show up you'll need to add the following lines to ~/.xscreensaver:" @echo ""; @for PROG in $(HACKS); do \ @@ -43,23 +52,30 @@ install: build-release doc-release ## Installs everything! @echo "(don't worry about duplicate lines, xscreensaver will clean that up)" clean: ## Deletes intermediate files (including compiled deps) - $(CARGO) $(CARGO_OPTS) clean + @$(CARGO) $(CARGO_OPTS) clean + @rm -f $(MANPAGES) $(MANPAGEZ) -check: ## Rebuilds and runs tests - $(MAKE) build - $(MAKE) test +check: build test ## Rebuilds and runs tests test: ## Runs tests (if they exist) - $(CARGO) $(CARGO_OPTS) test + @$(CARGO) $(CARGO_OPTS) test bench: ## Run benchmarks (if they exist) - $(CARGO) $(CARGO_OPTS) bench + @$(CARGO) $(CARGO_OPTS) bench + +docs: doc + +doc: $(MANPAGEZ) ## Builds documentation (if there is any) for the default target + @$(CARGO) $(CARGO_OPTS) doc --no-deps + +doc-release: $(MANPAGEZ) ## Builds documentation (if there is any) for release + @$(CARGO) $(CARGO_OPTS) doc --no-deps --release -doc: ## Builds documentation (if there is any) for the default target - $(CARGO) $(CARGO_OPTS) doc --no-deps +$(MANPAGES): %.$(MANSECTION): %.$(MANSECTION).md + $(MANPAGE.md) $< -o $@ -doc-release: ## Builds documentation (if there is any) for release - $(CARGO) $(CARGO_OPTS) doc --no-deps --release +$(MANPAGEZ): %.$(MANSECTION).gz: %.$(MANSECTION) + @gzip --keep --force $< help: @grep -E '^[a-zA-Z_-]+:.*?## .*$$' $(MAKEFILE_LIST) | sort | awk 'BEGIN {FS = ":.*?## "}; {printf "\033[36m%-25s\033[0m %s\n", $$1, $$2}' @@ -6,9 +6,35 @@ \___/_/\_\\__,_|_.__/ \___|_| \__,_|_| |_|\__| |_.__/ \___/ \_/ |_|_| |_|\___||___(_) -### Dependencies -Circa June 2016, this requires a patched version of the `glutin` window +### Build Dependencies and Installation + +It should be possible to build this project for most platforms using cargo +directly. Installation and XScreensaver integration probably only works on UNIX +machines (Linux, *BSD, etc). It's only been developed and tested on Debian +jessie, using the stable Rust toolchain (version 1.9). + +A patched version of the `glutin` OpenGL window generation library is required; +see below. + +The `pandoc` tool is required for building manpages. + +To just build (`--debug`) and run an indivual "hack", eg `exuberantbovines`: + + cargo run --bin exuberantbovines + +To build everything (`--release`) and install, first run: + + make install + +Then follow the directions about adding lines like the following to you +`~/.xscreensaver` to have hacks actually show up in, eg, `xscreensaver-demo`: + + GL: exuberantbovines --root \n\ + +### Installing Patched glutin Library + +Circa June 2016, this project requires a patched version of the `glutin` window creation library to allow re-using an existing X Window. This is only necessary for integration with X Windows, but the project won't build without it. @@ -22,3 +48,11 @@ Checkout the `feature-existing` branch from paths = ["/home/bnewbold/src/glutin"] +### Creating Your Own Hacks + +You'll need to create at least three files with the same base name ("$HACK"): + +- the rust sourcecode (src/bin/$HACK.rs) +- an XML config file (configs/$HACK.xml) +- a manpage in Markdown format (doc/$HACK.6.md) + diff --git a/extra/exuberantbovines.xml b/configs/exuberantbovines.xml index 49bc7d6..49bc7d6 100644 --- a/extra/exuberantbovines.xml +++ b/configs/exuberantbovines.xml diff --git a/doc/exuberantbovines.6.md b/doc/exuberantbovines.6.md new file mode 100644 index 0000000..dd45d0f --- /dev/null +++ b/doc/exuberantbovines.6.md @@ -0,0 +1,77 @@ +% exuberantbovines(6) | XScreenSaver manual + +NAME +==== + +**exuberantbovines** — rust port of bouncingcow + +SYNOPSIS +======== + +| **exuberantbovines** \[**-h**|**--help**] \[**--window-id** _id_] \[**--root**] +| \[**--wireframe**] \[**--fps**] + +DESCRIPTION +=========== + +This is a "hack" for the XScreensaver screen locker. It shows a bouncing (or at +least happily oscillating) bovine. + +OPTIONS +========= + +_exuberantbovines_ accepts the following options. Note that some long options (like +**root** and **window-id** can be passed with either a single dash (**-root**) +or a double-dash (**--root**) for backwards compatibility with XScreensaver. + +-h, --help + +: Prints brief usage information. + +--wireframe + +: Render in wireframe instead of solid. (UNIMPLEMENTED) + +--fps + +: Display the current frame rate, CPU load, and polygon count. (UNIMPLEMENTED) + + +FILES +===== + +*~/.xscreensaver* + +: Per-user configuration file. If there isn't a line for this hack in the + file, xscreensaver-demo won't find or run this hack. + +*/usr/share/xscreensaver/config/exuberantbovines.xml* + +: Configuration options for this hack + +ENVIRONMENT +=========== + +**XSCREENSAVER_WINDOW** + +: Optional ID number of the X window to draw into. + +Note that **XENVIRONMENT** and **DISPLAY** are *not* implemented. + +BUGS +==== + +A lot of features (like fps, root-window-finding, wireframe, etc) aren't +implemented yet. + +See GitHub Issues: <https://github.com/bnewbold/exuberant-bovines/issues> + +AUTHOR +====== + +Bryan Newbold <bnewbold@robocracy.org> + +SEE ALSO +======== + +**bouncingcow(6)**, **xscreensaver(1)**, **xscreensaver-demo(1)** |