update readme : add installation instructions
This commit is contained in:
parent
7ddc9a3006
commit
d9bbbfeea3
116
README.md
116
README.md
|
|
@ -18,24 +18,80 @@ author: xdrm-brackets
|
|||
|
||||
<!-- toc -->
|
||||
|
||||
* [I. Commands](#i-commands)
|
||||
* [I. How to use](#i-how-to-use)
|
||||
+ [1) Requirements](#1-requirements)
|
||||
+ [2) Installation](#2-installation)
|
||||
+ [3) Usage](#3-usage)
|
||||
* [1. Create build file](#1-create-build-file)
|
||||
* [2. Run on the target](#2-run-on-the-target)
|
||||
* [II. Commands](#ii-commands)
|
||||
+ [1) Comments](#1-comments)
|
||||
+ [2) package management](#2-package-management)
|
||||
+ [3) setup configuration](#3-setup-configuration)
|
||||
+ [4) service management](#4-service-management)
|
||||
+ [5) aliases](#5-aliases)
|
||||
+ [6) custom scripts](#6-custom-scripts)
|
||||
* [II. Path Expressions](#ii-path-expressions)
|
||||
+ [File Formats](#file-formats)
|
||||
+ [2) Install/remove Packages](#2-installremove-packages)
|
||||
+ [3) Setup configuration](#3-setup-configuration)
|
||||
+ [4) Service management](#4-service-management)
|
||||
+ [5) custom scripts](#5-custom-scripts)
|
||||
+ [6) Aliases](#6-aliases)
|
||||
* [III. Path Expressions](#iii-path-expressions)
|
||||
+ [1) Syntax](#1-syntax)
|
||||
+ [2) File Formats](#2-file-formats)
|
||||
- [Example](#example)
|
||||
|
||||
<!-- tocstop -->
|
||||
|
||||
----
|
||||
|
||||
### I. How to use
|
||||
|
||||
|
||||
### I. Commands
|
||||
|
||||
#### 1) Requirements
|
||||
|
||||
In order to install the `nix-amer` executable, you must have :
|
||||
|
||||
- any recent linux system (_has not been tested over other OS_)
|
||||
- `go` installed (_has not been tested under version **1.11**_)
|
||||
|
||||
|
||||
|
||||
#### 2) Installation
|
||||
|
||||
Simply launch the following command in any terminal
|
||||
|
||||
```bash
|
||||
$ go get -u github.com/xdrm-brackets/nix-amer
|
||||
```
|
||||
|
||||
> For those who don't know, it will load the project sources into `$GOPATH/src/github.com/xdrm-brackets/nix-amer` and compile into the executable at `$GOPATH/bin/nix-amer`.
|
||||
|
||||
|
||||
|
||||
#### 3) Usage
|
||||
|
||||
###### 1. Create build file
|
||||
|
||||
The first step is to write your build file according to the installation you want. While writing your build file you can check the syntax by using the `-dry-run` command-line argument as follows :
|
||||
|
||||
```bash
|
||||
$ nix-amer -p apt-get -dry-run <path/to/build/file>
|
||||
```
|
||||
|
||||
> The `-p` argument (package manager) is mandatory but it will have no effect in `-dry-run` mode. You can use for instance `apt-get` as a default.
|
||||
|
||||
|
||||
|
||||
###### 2. Run on the target
|
||||
|
||||
Once your build file is correct and fulfills your needs, you can log in to the target machine, install the nix-amer and run it with your build file. Nix-amer's rich and colorful command-line output will give you a good feedback to rapidly fix problems.
|
||||
|
||||
|
||||
|
||||
------
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
### II. Commands
|
||||
|
||||
Your whole setup remains in 1 only build file. Each line contains one instruction, the list of instructions is listed below.
|
||||
|
||||
|
|
@ -47,7 +103,7 @@ Each line beginning with one of the following characters : `[`, `#` or `;` is co
|
|||
|
||||
|
||||
|
||||
#### 2) package management
|
||||
#### 2) Install/remove Packages
|
||||
|
||||
These instructions allow you to interact with the package system available on your system.
|
||||
|
||||
|
|
@ -65,7 +121,7 @@ Remove the listed packages. If more than one, use spaces to separate package nam
|
|||
|
||||
|
||||
|
||||
#### 3) setup configuration
|
||||
#### 3) Setup configuration
|
||||
|
||||
This instruction allow you to set fields of configuration files without the need of an editor and in a developer-readable manner.
|
||||
|
||||
|
|
@ -77,7 +133,7 @@ Update a configuration file where \<expr\> is a dot-separated human-readable [pa
|
|||
|
||||
|
||||
|
||||
#### 4) service management
|
||||
#### 4) Service management
|
||||
|
||||
These instructions allow you to interact with the service system (_cf. [systemd](https://github.com/systemd/systemd)_).
|
||||
|
||||
|
|
@ -88,9 +144,21 @@ Perform the action on services. If more than one, use spaces to separate service
|
|||
|
||||
|
||||
|
||||
#### 5) aliases
|
||||
#### 5) custom scripts
|
||||
|
||||
The file format allows you to create aliases to file paths for more readability in the [path expression](#ii-path-expressions) or with the [`run` command](#6-custom-scripts).
|
||||
These instructions allow you to use custom scripts for complex operations.
|
||||
|
||||
```
|
||||
run <script>
|
||||
```
|
||||
|
||||
Execute the executable located at the path \<script\>. If script is an [alias](#6-aliases) it will resolve to its path
|
||||
|
||||
|
||||
|
||||
#### 6) Aliases
|
||||
|
||||
The file format allows you to create aliases to file paths for more readability in the [path expression](#ii-path-expressions) or with the [`run` command](#5-custom-scripts).
|
||||
|
||||
```
|
||||
alias name /path/to.file
|
||||
|
|
@ -102,36 +170,28 @@ Create the alias `name` which resolves to the path `/path/to.file`.
|
|||
|
||||
|
||||
|
||||
#### 6) custom scripts
|
||||
|
||||
These instructions allow you to use custom scripts for complex operations.
|
||||
|
||||
```
|
||||
run <script>
|
||||
```
|
||||
|
||||
Execute the executable located at the path \<script\>. If script is an [alias](#5-aliases) it will resolve to its path
|
||||
|
||||
|
||||
|
||||
----
|
||||
|
||||
|
||||
|
||||
### II. Path Expressions
|
||||
### III. Path Expressions
|
||||
|
||||
|
||||
#### 1) Syntax
|
||||
The syntax is pretty fast-forward, it uses 2 levels (file, fields) to find your configuration line : `location_or_alias@fields`.
|
||||
|
||||
| Field | Description | Example |
|
||||
| --------- | :----------------------------------- | -------------------------- |
|
||||
| `location_or_alias` | Path to the configuration file to edit. The file will be created if not found. If the path is an [alias](#5-aliases) created before in the file, it will resolve to the alias value as a filename. | `/etc/nginx/nginx.conf`, `some-alias` |
|
||||
| `location_or_alias` | Path to the configuration file to edit. The file will be created if not found. If the path is an [alias](#6-aliases) created before in the file, it will resolve to the alias value as a filename. | `/etc/nginx/nginx.conf`, `some-alias` |
|
||||
| `fields` | Dot-separated chain of strings that match a configuration field. If the field does not point to a raw field but an existing field container, the \<value\> will replace the group with a text value. | `AllowGroups`, `http.gzip` |
|
||||
|
||||
> The `fields` is processed only for known file formats listed in this [section](#file-formats).
|
||||
> The `fields` is processed only for known file formats listed in this [section](#2-file-formats).
|
||||
|
||||
|
||||
|
||||
#### File Formats
|
||||
#### 2) File Formats
|
||||
|
||||
Configuration files can be written according to some standards or application-specific syntax. This tool uses standard and third-party to parse the following formats :
|
||||
|
||||
|
|
|
|||
Loading…
Reference in New Issue