Home.md

@@ -0,0 +1,46 @@
+# cfnpp - cloudformation plus plus
+A tool for making it easier to write, re-use, and template CloudFormation stacks.
+
+## Why?
+Writing and maintaining CloudFormation stacks is a large part of my job and is also tedious.
+
+Why not use existing tools (e.g., Terraform)? Abstracting away the CloudFormation stuff _too_ much introduces more opportunities for bugs to creep in and leaves you operating several months behind on updates to AWS services and CloudFormation itself while you wait for upstream to implement the changes.
+
+But mainly I had some free time that needed filling.
+
+## What?
+At its core, it's a superset of YAML implemented in a way that's compatible with existing YAML parsers. You can put in a valid YAML document, and get the same document back out. Everything added is additional functionality on top of that. You don't need to rewrite your existing templates in a new language, but can start to use the additional functionality right away wherever it provides value.
+
+It adds the ability to [join multiple files together](Merging) and [control how they are merged](Merging#Functions) and [use variables](Variables), [expressions](Expressions) and [conditional statements and other functions](Functions).
+
+## How do I run it?
+
+### Pre-requisites
+
+This tool requires the following packages:
+
+- php 8.0+ (may work on lower versions, but untested)
+- php-fileinfo
+- php-json
+- php-zlib
+- composer (if not running a pre-built phar)
+
+All of these are likely available in your distro's package manager. As long as you have PHP installed, it will notify you of any additional missing dependencies when you run the phar.
+
+### Running Phar
+
+1. Download phar
+2. Run `./cfnpp stack:compile <input_file> <output_file>`
+
+### Running Source
+
+1. Clone repository
+2. Install dependencies: `composer install`
+3. Run `./cfnpp stack:compile <input_file> <output_file>`
+
+### Building Phar
+
+1. Clone repository
+2. Install dependencies: `composer install`
+3. Run `./cfnpp app:build` and answer the prompts
+4. Built phar is at `./builds/`