aboutsummaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
-rw-r--r--.gitignore2
-rw-r--r--Makefile60
-rw-r--r--README.txt38
-rw-r--r--configs/exuberantbovines.xml (renamed from extra/exuberantbovines.xml)0
-rw-r--r--doc/exuberantbovines.6.md77
5 files changed, 153 insertions, 24 deletions
diff --git a/.gitignore b/.gitignore
index 64def30..4a29496 100644
--- a/.gitignore
+++ b/.gitignore
@@ -1,4 +1,6 @@
target/
+doc/*.6
+doc/*.6.gz
*.o
*.a
diff --git a/Makefile b/Makefile
index 0cb65a1..481ccc3 100644
--- a/Makefile
+++ b/Makefile
@@ -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}'
diff --git a/README.txt b/README.txt
index 1aac5e3..5483263 100644
--- a/README.txt
+++ b/README.txt
@@ -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)**