version v2.0

.gitattributes

@@ -0,0 +1,10 @@
+*.tmpl linguist-language=tcl
+
+/README.md export-ignore
+/tests export-ignore
+/templates export-ignore
+/examples export-ignore
+/_config.yml export-ignore
+/.travis.yml export-ignore
+/.gitattributes export-ignore
+/.gitignore export-ignore

.travis.yml

@@ -0,0 +1,8 @@
+dist: xenial
+language: generic
+
+script:
+  - ./tests/test_init.sh
+  - ./tests/test_simple.sh
+  - ./tests/test_advanced.sh
+  - ./tests/test_version_attributes.sh

README.md

@@ -1,23 +1,28 @@
-# Intro
+# mkiapp
+[![Travis Build Status](https://img.shields.io/travis/com/simonkowallik/mkiapp/master.svg?label=travis%20build)](https://travis-ci.com/simonkowallik/mkiapp)
+[![Releases](https://img.shields.io/github/release/simonkowallik/mkiapp.svg)](https://github.com/simonkowallik/mkiapp/releases)
+[![Latest Release Date](https://img.shields.io/github/release-date/simonkowallik/mkiapp.svg?color=blue)](https://github.com/simonkowallik/mkiapp/releases/latest)
+[![Commits since latest release](https://img.shields.io/github/commits-since/simonkowallik/mkiapp/latest.svg)](https://github.com/simonkowallik/mkiapp/commits)
+## Intro
 `mkiapp` simplifies the process of "putting the pieces together" when developing iApps.
 When developing larger iApps you most likely want to split the separate sections into files and not use the WebUI to develop it either.
 `mkiapp` combines separate files for presentation, implementation, macro and help section into a target iApp, which can be loaded via the WebUI or tmsh. It provides advanced features to generate iApps and dynamically replace data within it.
 
 `mkiapp` itself relies on `bash`, `awk` and other common command line tools - available on most platforms.
 
 
-# Not convinced? Watch this demo!
+## Not convinced? Watch this demo!
 <p align="center">
     <img src="https://simonkowallik.github.io/mkiapp/examples/demo.svg">
 </p>
 
 
-# Installation
+## Installation
 
-## Manual
+### Manual
  Copy the `mkiapp` file to any place in your `$PATH`. You can also fetch a [release](https://github.com/simonkowallik/mkiapp/releases) .zip or .tar.gz instead.
 
-## Homebrew / Linuxbrew
+### Homebrew / Linuxbrew
 You can install `mkiapp` via homebrew and linuxbrew.
 
     brew install simonkowallik/f5/mkiapp
@@ -26,17 +31,17 @@ If you want to receive updates when running `brew update` add my tap with `brew
 
 > ***Info for fish users:*** If you have trouble running `mkiapp` with fish, either create an alias (`alias mkiapp (which mkiapp)`) or execute `mkiapp` with it's full path (eg. `/usr/local/bin/mkiapp`).
 
-# Details
+## Details
 To generate the target iApp, which can be used on an F5 BIG-IP device, `mkiapp` uses a so called `iApp Skeleton Template`.
 The `iApp Skeleton Template` can be loaded from a file or the `builtin iApp Skeleton Template` is used, which should be sufficient for most use-cases.
 `mkiapp` reads its settings from the `.mkiapp configuration file` in the current working directory (similar to `git`).
 
-## The iApp Skeleton Template
+### The iApp Skeleton Template
 The `iApp Skeleton Template` contains the general structure of a target iApp. `<placeholders>` are used within the `iApp Skeleton Template` to include `Section Skeleton Files` and `iApp Skeleton Template Variables`.
 
 You can create your own `iApp Skeleton Template`, see further below if required.
 
-## The Section Skeleton Files
+### The Section Skeleton Files
 The `Section Skeleton Files` reference to a file on the filesystem. This file content is included into the `iApp Skeleton Template` to fill four iApp Sections:
 - presentation (required)
 - implementation (required)
@@ -45,7 +50,7 @@ The `Section Skeleton Files` reference to a file on the filesystem. This file co
 
 `Section Skeleton Files` are technically represented by a shell variable, the variable content is the file on the filesystem.
 
-## The Skeleton Template Variables
+### The Skeleton Template Variables
 `Skeleton Template Variables` define a single value within the `iApp Skeleton Template`, for example `Skeleton Template Variables` are used to define:
 - iApp Name
 - Minimum BIG-IP Version
@@ -56,7 +61,7 @@ Technically `Skeleton Template Variables` are shell variables.
 
 You can define additional `Skeleton Template Variables` for use in custom `iApp Skeleton Templates` if needed.
 
-## < placeholders >
+### < placeholders >
 `Section Skeleton Files` and `Skeleton Template Variables` have a corresponding `<placeholder>` within the `iApp Skeleton Template`.
 
 The `<placeholder>` is replaced by the actual value of `Skeleton Template Variable` or content of the `Section Skeleton File`.
@@ -79,7 +84,7 @@ With exception to `<>` the `<placeholder>` names and `Skeleton Template Variable
 
 The variables are defined and read from the `.mkiapp configuration file`. 
 
-## .mkiapp configuration file
+### .mkiapp configuration file
 The `.mkiapp configuration file` can be created by running `mkiapp init` and contains the shell variables above.
 It further allows to customise `mkiapp` behaviour.
 
@@ -118,13 +123,14 @@ Based on the configuration above, `mkiapp config MKIAPP_IAPP_NAME` would print `
 
 Of course you can just use your favorite editor to modify the file.
 
-# Usage
+## Usage
 `mkiapp --help` will provide you with the following help.
 
-    usage: mkiapp [init] [init-files] [showbuiltin] [config [edit] [<key>] [<key> <value>]] [-t|--template <file>] [--(no-)impl|--(no-)implementation] [--(no-)apl|--(no-)presentation] [--(no-)macro] [--(no-)html] [-h|--help] [-v|--version]
+    usage: mkiapp [init] [init-files] [showbuiltin] [showmakefile] [config [edit] [<key>] [<key> <value>]] [-t|--template <file>] [--(no-)impl|--(no-)implementation] [--(no-)apl|--(no-)presentation] [--(no-)macro] [--(no-)html] [-h|--help] [-v|--version]
                    init:    initialize current working directory for mkiapp
              init-files:    create Section Skeleton Files in current working directory
             showbuiltin:    print builtin iApp Skeleton Template
+           showmakefile:    print example Makefile
                  config:    no arguments: prints full configuration
                             edit: opens configuration in $EDITOR
                             <key>: prints its value
@@ -158,28 +164,39 @@ There are a couple of other options available to generate your iApp. `--implemen
 
 > ***Note:*** You always have to run `mkiapp` in the directory you "initialised" (contains the `.mkiapp configuration file`), similar to `git`.
 
-## TODO: deploy iApp template to an F5 BIG-IP
-TODO: elaborate on this
-1. scp ./my_iapp_template.tmpl user@bigip:/tmp/my_iapp_template.tmpl
-2. ssh user@bigip 'tmsh load sys config merge verify file /tmp/my_iapp_template.tmpl'
-3. ssh user@bigip 'tmsh load sys config merge file /tmp/my_iapp_template.tmpl'
+### Deploy iApp template to an F5 BIG-IP
+Various ways are available to deploy the iApp template on an F5 BIG-IP.
+While detailing all possibilities is out of scope of this tool, here is a short quide using ssh/command line:
 
-best to use with ssh public-key authentication
+1. copy the iapp template to the BIG-IP /tmp directory (the directory matters for step 2+3!)
+```sh
+scp ./my_iapp_template.tmpl root@bigip:/tmp/my_iapp_template.tmpl
+```
 
-TODO IDEA:
-create 'deploy' arg to execute above, allow with -- and --no flags
-'deploy' takes one optional argument: user@bigip otherwise reads it from MKIAPP_DEPLOY_BIGIP
+2. verify that the template has no syntax errors before merging it
+```sh
+ssh root@bigip 'tmsh load sys config merge verify file /tmp/my_iapp_template.tmpl'
+```
 
-# Examples
-Two examples are located in the examples folder of this repository to demonstrate the use of `mkiapp`.
+3. merge iapp template into current configuration (note that this overwrites any existing template which has the same iapp name)
+```sh
+ssh root@bigip 'tmsh load sys config merge file /tmp/my_iapp_template.tmpl'
+```
+
+Best to use with ssh public-key authentication.
 
+Also checkout the examples/Makefile, which provides a simple way to copy the built iapp to a BIG-IP.
+If you like it `mkiapp showmakefile > ./Makefile` will build it for you!
+
+## Examples
+Two examples are located in the examples folder of this repository to demonstrate the use of `mkiapp`.
 
-# Extensibility and customisation
+## Extensibility and customisation
 The `mkiapp` functionality can be further extended. `mkiapp` uses the bash `source` command to include `.mkiapp`, which gives you a lot of power and control over `mkiapp`.
 
 A simple use-case could be to add additional `MKIAPP_VAR_` variables when you need a custom `iApp Skeleton Template`.
 
-### Example
+#### Example
 If you want to add the a description to the generated iApp Template you could come up with a new variable, let's say `MKIAPP_VAR_DESCRIPTION`. The corresponding placeholder would be `<MKIAPP_VAR_DESCRIPTION>`.
 
 Let's first add the variable with a static value:
@@ -195,10 +212,10 @@ Another option would be to not configure `MKIAPP_VAR_DESCRIPTION` in the `.mkiap
 
 > ***Important:*** No matter which technique you decide on using, make sure the resulting value in the iApp template follows the iApp syntax.
 
-## More advanced customisation
+### More advanced customisation
 Furthermore `$MKIAPP_ENV_` variables allow content replacement within the generated iApp. This allows you to dynamically change content which is included form the `Section Skeleton Files` during the `mkiapp` iApp generation process.
 
-### Example
+#### Example
 
 Add `<MKIAPP_ENV_PRESENTATION_GITHASH>` placeholder to a section in the presentation `Section Skeleton File`:
 
@@ -232,7 +249,7 @@ For example the placeholder `<MKIAPP_FILE_BASH_SCRIPT>` could be used to include
 
 `<MKIAPP_ENV_>` placeholders can be used in files included by `<MKIAPP_FILE_>` as well. :-)
 
-## Creating your own iApp Skeleton Template
+### Creating your own iApp Skeleton Template
 If you need a custom `iApp Skeleton Template`, you can start off by using the `builtin` one.
 The builtin template can be listed with `mkiapp showbuiltin`:
 

examples/Makefile

@@ -0,0 +1,18 @@
+BUSER ?= root
+BIGIP ?= 192.168.0.245
+
+all:
+	mkiapp > iapp.tmpl
+
+build: all
+
+upload:
+	scp iapp.tmpl $(BUSER)@$(BIGIP):/tmp/
+
+verify: upload
+	ssh $(BUSER)@$(BIGIP) 'tmsh load sys config merge verify file /tmp/iapp.tmpl'
+
+deploy: verify
+	ssh $(BUSER)@$(BIGIP) 'tmsh load sys config merge file /tmp/iapp.tmpl'
+
+install: deploy

examples/README.md

@@ -0,0 +1,30 @@
+# Makefile
+This Makefile provides you with an example for mkiapp using GNU make.
+
+It allows to build the iapp by typing `make` or `make build`.
+`make verify` uploads the iapp template to your test BIG-IP using scp and runs `tmsh load /sys config merge verify`.
+`make deploy` does the same as `make verify` plus it actually merges it.
+*Note:* that this will overwrite any exsting iapp template with the same name!
+
+To configure your target BIGIP set it in the Makefile or use the environment variable `BIGIP` to overwrite the configured value in the Makefile. Do the same for `BUSER`.
+
+Example:
+```sh
+# make
+mkiapp > iapp.tmpl
+
+# make verify
+scp iapp.tmpl simon@192.168.0.245:/tmp/
+ssh simon@192.168.0.245 tmsh load sys config merge verify file /tmp/iapp.tmpl
+
+# BUSER=admin BIGIP=192.0.2.1 make deploy
+scp iapp.tmpl admin@192.0.2.1:/tmp/
+ssh admin@192.0.2.1 tmsh load sys config merge verify file /tmp/iapp.tmpl
+ssh admin@192.0.2.1 tmsh load sys config merge file /tmp/iapp.tmpl
+```
+
+# simple
+A simple mkiapp demo, see directory for more details.
+
+# advanced
+A more advanced mkiapp demo, see directory for more details.

mkiapp

@@ -1,10 +1,33 @@
 #!/usr/bin/env bash
 
-VERSION="1.1"
+VERSION="2.0"
 HOMEPAGE="https://github.com/simonkowallik/mkiapp"
 PROGRAM=$(basename "$0")
 CONFIGFILE=".mkiapp"
 
+# example Makefile
+_Makefile=$(cat <<'EOF'
+BUSER ?= root
+BIGIP ?= 192.168.0.245
+
+all:
+	mkiapp > iapp.tmpl
+
+build: all
+
+upload:
+	scp iapp.tmpl $(BUSER)@$(BIGIP):/tmp/
+
+verify: upload
+	ssh $(BUSER)@$(BIGIP) 'tmsh load sys config merge verify file /tmp/iapp.tmpl'
+
+deploy: verify
+	ssh $(BUSER)@$(BIGIP) 'tmsh load sys config merge file /tmp/iapp.tmpl'
+
+install: deploy
+EOF
+)
+
 # builtin iapp skeleton
 _builtinSkeleton=$(cat <<'EOF'
 #TMSH-VERSION: <MKIAPP_VAR_TMSH_VERSION>
@@ -60,10 +83,10 @@ editcmd="$(command -v "$EDITOR" || command -v vim || command -v vi || command -v
 # init mkiapp function
 function mkinit() {
 export MKIAPP_IAPP_NAME=$(basename "$(pwd)")
-export MKIAPP_SECTIONFILE_PRESENTATION="$(ls presentation\.* 2>/dev/null || echo 'presentation.tcl' | head -1)"
-export MKIAPP_SECTIONFILE_IMPLEMENTATION="$(ls implementation\.* 2>/dev/null || echo 'implementation.tcl' | head -1)"
-export MKIAPP_SECTIONFILE_HELP="$(ls help\.* 2>/dev/null || echo 'help.html' | head -1)"
-export MKIAPP_SECTIONFILE_MACRO="$(ls macro\.* 2>/dev/null || echo 'macro.tcl' | head -1)"
+export MKIAPP_SECTIONFILE_PRESENTATION="$(ls presentation\.* 2>/dev/null || ls src/presentation\.* 2>/dev/null || ls source/presentation\.* 2>/dev/null || echo 'presentation.tcl' | head -1)"
+export MKIAPP_SECTIONFILE_IMPLEMENTATION="$(ls implementation\.* 2>/dev/null || ls src/implementation\.* 2>/dev/null || ls source/implementation\.* 2>/dev/null || echo 'implementation.tcl' | head -1)"
+export MKIAPP_SECTIONFILE_HELP="$(ls help\.* 2>/dev/null || ls src/help\.* 2>/dev/null || ls source/help\.* 2>/dev/null || echo 'help.html' | head -1)"
+export MKIAPP_SECTIONFILE_MACRO="$(ls macro\.* 2>/dev/null || ls src/macro\.* 2>/dev/null || ls source/macro\.* 2>/dev/null || echo 'macro.tcl' | head -1)"
 export MKIAPP_VAR_TMSH_VERSION="11.6.0"
 export MKIAPP_VAR_MINVERSION="none"
 export MKIAPP_VAR_MAXVERSION="none"
@@ -146,7 +169,7 @@ function mkiapp_config() {
         $awkcmd -v pattern="^export ${1}=.*\$" 'BEGIN {code=1} { if ($0 ~ pattern) {code=0} } END {exit code}' "$CONFIGFILE" \
             && $awkcmd -v pattern="^export ${1}=.*\$" -v value="export ${1}=\"${2}\"" \
                 '{ if ($0 ~ pattern) {gsub(pattern, value)} print }' \
-                "$CONFIGFILE" | tee "$CONFIGFILE" >/dev/null \
+                "$CONFIGFILE" > "${CONFIGFILE}.tmp" && mv -f "${CONFIGFILE}.tmp" "$CONFIGFILE"  >/dev/null \
             || echo "export ${1}=\"${2}\"" >> "$CONFIGFILE"
     else
         # this should never happen
@@ -155,10 +178,11 @@ function mkiapp_config() {
 }
 
 function print_help() {
-    printf 'usage: %s [init] [init-files] [showbuiltin] [config [edit] [<key>] [<key> <value>]] [-t|--template <file>] [--(no-)impl|--(no-)implementation] [--(no-)apl|--(no-)presentation] [--(no-)macro] [--(no-)html] [-h|--help] [-v|--version]\n' "$PROGRAM"
+    printf 'usage: %s [init] [init-files] [showbuiltin] [showmakefile] [config [edit] [<key>] [<key> <value>]] [-t|--template <file>] [--(no-)impl|--(no-)implementation] [--(no-)apl|--(no-)presentation] [--(no-)macro] [--(no-)html] [-h|--help] [-v|--version]\n' "$PROGRAM"
     printf '%20s    %s\n' "init:" "initialize current working directory for $PROGRAM"
     printf '%20s    %s\n' "init-files:" "create Section Skeleton Files in current working directory"
     printf '%20s    %s\n' "showbuiltin:" "print builtin iApp Skeleton Template"
+    printf '%20s    %s\n' "showmakefile:" "print example Makefile"
     printf '%20s    %s\n' "config:" "no arguments: prints full configuration"
     printf '%24s%s\n' "" "edit: opens configuration in \$EDITOR"
     printf '%24s%s\n' "" "<key>: prints its value"
@@ -243,6 +267,11 @@ function parse_cmd() {
                 echo "$_builtinSkeleton"
                 exit 0
                 ;;
+            showmakefile|makefile)
+                test $# -gt 1 && err_exit "Too many arugments '$_arg'."
+                echo "$_Makefile"
+                exit 0
+                ;;
             config)
                 test $# -gt 3 && err_exit "Too many arugments '$_arg'."
                 if [[ $_initialized == "false" ]]; then

tests/template.tmpl

@@ -0,0 +1,33 @@
+#TMSH-VERSION: <MKIAPP_VAR_TMSH_VERSION>
+
+cli admin-partitions {
+    update-partition Common
+}
+sys application template /Common/<MKIAPP_IAPP_NAME> {
+    actions {
+        definition {
+            html-help {
+<MKIAPP_SECTIONFILE_HELP>
+            }
+            implementation {
+<MKIAPP_SECTIONFILE_IMPLEMENTATION>
+            }
+            macro {
+<MKIAPP_SECTIONFILE_MACRO>
+            }
+            presentation {
+<MKIAPP_SECTIONFILE_PRESENTATION>
+            }
+            role-acl none
+            run-as none
+        }
+    }
+    description none
+    ignore-verification false
+    requires-bigip-version-max <MKIAPP_VAR_MAXVERSION>
+    requires-bigip-version-min <MKIAPP_VAR_MINVERSION>
+    requires-modules { <MKIAPP_VAR_REQUIRED_MODULES> }
+    signing-key none
+    tmpl-checksum none
+    tmpl-signature none
+}

tests/test_advanced.sh

@@ -0,0 +1,28 @@
+#!/usr/bin/env bash
+set -ev
+
+# prepare for tests
+export PATH="$PATH:$(pwd)"
+export BASEDIR=$(pwd)
+cd ./examples/advanced
+
+# init mkiapp in current directory
+mkiapp init >/dev/null || exit 1
+
+# update iapp name
+mkiapp config MKIAPP_IAPP_NAME adv_test || exit 1
+grep 'MKIAPP_IAPP_NAME.*adv_test.*' .mkiapp >/dev/null || exit 1
+
+# update section files
+mkiapp config MKIAPP_SECTIONFILE_IMPLEMENTATION impl.tcl || exit 1
+mkiapp config MKIAPP_SECTIONFILE_MACRO irule_macro.tcl || exit 1
+
+# add MKIAPP_FILE for HTML response
+mkiapp config MKIAPP_FILE_HTMLRESPONSE ./htmlresponse.html || exit 1
+
+# export current version & generate iApp
+export MKIAPP_ENV_PRESENTATION_VERSION=v01
+mkiapp -t $BASEDIR/tests/template.tmpl > iapp.tmpl || exit 1
+
+# check if iApp differs from expected result
+diff $BASEDIR/tests/test_advanced.tmpl iapp.tmpl || exit 1