From 91052dfc0d9e23b2baf499f6c5aab21b1544a236 Mon Sep 17 00:00:00 2001 From: Trygve Laugstøl Date: Sat, 26 Oct 2013 19:31:49 +0200 Subject: o Adding a man page on internals. --- Makefile | 4 +- README.md | 168 +------------------------------------------------- docs/Makefile | 17 +++-- docs/app-cat-conf.txt | 8 +++ docs/app.txt | 27 +------- docs/appinternals.txt | 33 ++++++++++ docs/asciidoc.conf | 4 +- 7 files changed, 62 insertions(+), 199 deletions(-) create mode 100644 docs/appinternals.txt diff --git a/Makefile b/Makefile index 49a1896..edf76c8 100644 --- a/Makefile +++ b/Makefile @@ -18,11 +18,11 @@ test: $(TESTS) .PHONY: test clean: - @make -C docs clean + @make -s -C docs clean .PHONY: clean docs: - @make -C docs + @make -s -C docs .PHONY: docs define set_header diff --git a/README.md b/README.md index c4a83e9..f36feea 100644 --- a/README.md +++ b/README.md @@ -1,166 +1,2 @@ -Installation ------------- - - git clone http://.../app.sh.git - - mkdir /opt/apps - cd /opt/apps - ln -s .../app.sh.git/app.sh app.sh - -NOTE: The bash completion is not perfect yet. - - echo 'source .../app.sh.git/app_completion' >> ~/.bashrc - -Or was it `~/.bash_profile`? hmm - -TODOs ------ - -* Support installation-wide settings. Useful for shared environment - settings etc (PATH). - -* Add support for hooks in .app/hooks. Example hooks: - * Diff config. Save a backup of the config on installtaion. - * Copy the configuration from the previous installation. - -* Support changing current version. - -* Document app.sh - * Concept: config. group, key and value. - * Scriptable - -* init.d support - register the application under /etc/init.d on - installation. Should probably be a plugin. - -* Support -h for all applicable methods to show the help/usage. - -* Rename "scripts/" to handlers or something similar. Perhaps just - remove it entirely. - -* Document how the operate method (custom pid-method stuff) can see - its own output for debugging. - -Commands --------- - -### `instance` - -#### `install` - -#### `upgrade` - -Tries to upgrade all instances where the version doesn't match the resolved version. - -#### `list` - -#### `list-versions` - -#### `set-current` - -#### `remove` - -Not implemented - -### `conf` - -#### `get` - - ./app -n $n -i $i conf get - -#### `set` - - ./app -n $n -i $i conf set group.key value - -#### `delete` - - ./app -n $n -i $i conf delete group.key - -### `operate` - -The operate sub-methods are provided by the application. - -#### Supported methods by `pid-method` - -#### `start` - -#### `stop` - -TODO: support -f flag that doesn't exit with 1 if the app is not running. - -#### `status` - -### `foreach` - -Runs the given command for each of the selected instances. - -Method Contract ---------------- - -### Environment variables you can depend on - -* `APPSH_NAME` -* `APPSH_INSTANCE` -* `APPSH_METHOD` - -Unclassified: - -* `APPSH_HOME` -* `APPSH_APPS` - -Directory Hierarchy -------------------- - -### Current - -App.sh is installed through cloning the git repository and/or -unpacking a tarball from the git repository. The directory that -contains the app.sh libraries is known as `$APPSH_HOME`. - -App.sh related: - - ./ The root of an application set. Known as $APPSH_APPS - ./app The app script, symlinked from your git clone directory - ./.app/lib bash libraries used by app.sh and methods - ./.app/var runtime data - -Applications: - - ./// - Known as $APPSH_INSTANCE_HOME - current -> - symlink to the currently installed app - versions/ - collection with all installed versions - 1.0/ - A installed version. The zip file is unzipped here. - root/ - The current directory when executing methods and scripts - scripts/ - 1.1/ - 2.0/ - -Creating Apps -------------- - -"App bundles" are basically just zip file with a specific layout. It -has to contain at least a `root/` directory which contains your -application. It can contain anything. The `current` symlink will point -to this directory. - -The bundle can also contain a special `scripts` directory which -contains scripts that's run durtion package operations. Only -`postinstall` is currently supported. - -Zip File Tree -============= - - root/ - bin/ - myapp - etc/ - config - scripts/ - postinstall - -Managing Apps -------------- - -Setting Environment Variables ------------------------------ - - app -n .. -i .. conf +See docs/app.txt. Run `make docs` to generate a HTML version if you +have asciidoc installed. diff --git a/docs/Makefile b/docs/Makefile index 2a62f18..f340323 100644 --- a/docs/Makefile +++ b/docs/Makefile @@ -1,6 +1,8 @@ TXT=$(wildcard *.txt) +# Expand target section from heading of each page +MAN=$(shell ls *.txt|xargs -n 1 head -n 1|sed "s,\(.*\)(\([0-9]\)),\1.\2,") HTML=$(patsubst %.txt,%.html,$(TXT)) -MAN=$(patsubst %.txt,%.1,$(TXT)) + all: $(HTML) $(MAN) %.html: %.txt @@ -8,8 +10,15 @@ all: $(HTML) $(MAN) @asciidoc -f asciidoc.conf --backend=html5 $< %.1: %.txt - @echo a2x $< - @a2x --format manpage $< + $(call man,$<) + +%.7: %.txt + $(call man,$<) + +define man + @echo a2x $(1) + @a2x --format manpage $(1) +endef clean: - rm -rf $(wildcard *.html) $(wildcard *.1) + rm -rf $(wildcard *.html) $(wildcard *.1) $(wildcard *.7) diff --git a/docs/app-cat-conf.txt b/docs/app-cat-conf.txt index ec2c4f9..0b4f83a 100644 --- a/docs/app-cat-conf.txt +++ b/docs/app-cat-conf.txt @@ -45,6 +45,14 @@ LOCATIONS AND DEFAULT FILES * '.app/config' +TODOs +----- + +Support comments:: + 1) ignore comments (lines that start with #), 2) add a flag (-C) to + include comments in the output but still filter the lines. (2) is + required for app-conf set to work. (1) can be done first. + SEE ALSO -------- diff --git a/docs/app.txt b/docs/app.txt index fb77174..c0d92f6 100644 --- a/docs/app.txt +++ b/docs/app.txt @@ -55,30 +55,6 @@ CHANGING VERSION OF AN APPLICATION `app-sync-version` will first run the resolver to resolve the version and if that has changed, it will download and install the new version. -INTERNALS ---------- - -Concepts: - -resolver:: - Something that takes a version and resolves it to a specific - version. Makes it possible to depend on a development version - which is resolved later on. - -Configuration properties: - -`app.version`:: - The unresolved version of the application. Configured when the - application is installed. - -`app.resolved_version`:: - The resolved version of the application. Is updated by the - resolved configured for the project. - -`app.installed_version`:: - The installed version of the application. Is updated by - `app-set-version`. - TODOs ----- @@ -92,6 +68,7 @@ TODOs SEE ALSO -------- -linkman:app-conf[1] +linkman:app-conf[1], +linkman:appinternals[1], // vim: set ft=asciidoc: diff --git a/docs/appinternals.txt b/docs/appinternals.txt new file mode 100644 index 0000000..743cb03 --- /dev/null +++ b/docs/appinternals.txt @@ -0,0 +1,33 @@ +appinternals(7) +=============== + +NAME +---- +appinternals - Appsh internals + +DESCRIPTION +----------- + +Concepts: + +resolver:: + Something that takes a version and resolves it to a specific + version. Makes it possible to depend on a development version + which is resolved later on. + +Configuration properties: + +`app.version`:: + The unresolved version of the application. Configured when the + application is installed. + +`app.resolved_version`:: + The resolved version of the application. Is updated by the + resolved configured for the project. + +`app.installed_version`:: + The installed version of the application. Is updated by + `app-set-version`. + + +// vim: set ft=asciidoc: diff --git a/docs/asciidoc.conf b/docs/asciidoc.conf index 8622db4..724524a 100644 --- a/docs/asciidoc.conf +++ b/docs/asciidoc.conf @@ -11,8 +11,8 @@ endif::backend-docbook[] ifdef::backend-html5[] -#[attributes] -#relative-ext=.html +[attributes] +relative-ext=.html [linkman-inlinemacro] {target}{0?({0})} -- cgit v1.2.3