Skip to content

Commit 204afad

Browse files
cytopiacytopia
committed
Update docs for install.yml
1 parent a470824 commit 204afad

File tree

2 files changed

+237
-6
lines changed

2 files changed

+237
-6
lines changed

‎doc/contributor/PHP-EXT-install.yml.md

Lines changed: 21 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -29,16 +29,21 @@ already_avail: "{{ php_all_versions }}"
2929
**Example:** Overwriting `git_ref` for a specific version
3030
```yaml
3131
already_avail: [5.2]
32+
3233
all:
3334
type: git
3435
git_url: https://github.com/phalcon/cphalcon
3536
git_ref: master
37+
3638
# PHP 8.1 is using a different git_ref
3739
8.1:
40+
type: git
3841
git_ref: v1.0.0
42+
3943
# PHP 8.0 is using a different git_ref dynamically with latest tag found
4044
# See the usage of supported shell code
4145
8.0:
46+
type: git
4247
git_ref: $( git tag | sort -V | tail -1 )
4348
```
4449

@@ -53,7 +58,7 @@ The following keys can be added below: `all`, `8.2`, `8.1`, `8.0`, `7.4`, ...
5358
| `post` | No | Yes | Specify a shell command to be run after module installation. |
5459
| `build_dep` | No | No | Array Debian packages required to build the module (they won't be present in the final image - only used to built the module) If you don't need any, assign it an empty array: `build_dep: []`. |
5560
| `run_dep` | No | No | Array Debian packages required for the module run-time (they won't be present during the build stage - only in the final image). If you don't need any, assign it an empty array: `run_dep: []`. |
56-
| `type` | **Yes** | No | On of the following types to build the module: `builtin`, `pecl`, `git`, `custom`. |
61+
| `type` | **Yes** | No | On of the following types to build the module: `builtin`, `pecl`, `git` or `custom`. |
5762

5863
**Example:**
5964
```yaml
@@ -65,6 +70,7 @@ all:
6570
rm -f /tmp/file.txt \
6671
build_dep: [libmcrypt-dev]
6772
run_dep: [libmcrypt4]
73+
6874
8.1:
6975
type: builtin
7076
build_dep: []
@@ -82,9 +88,11 @@ all:
8288
```yaml
8389
all:
8490
type: builtin
91+
8592
8.1:
8693
type: builtin
8794
configure: --with-jpeg --with-png
95+
8896
8.0:
8997
type: builtin
9098
configure: --with-jpeg
@@ -105,6 +113,7 @@ all:
105113
command: echo "/usr" | pecl install amqp
106114
build_dep: [librabbitmq-dev]
107115
run_dep: [librabbitmq4]
116+
108117
5.5:
109118
type: pecl
110119
version: 1.9.3
@@ -124,16 +133,22 @@ all:
124133
**Example:**
125134
```yaml
126135
already_avail: [5.2]
136+
137+
# Default for all PHP versions if no overwrite exists
127138
all:
128139
type: git
129140
git_url: https://github.com/phalcon/cphalcon
130141
git_ref: master
131-
# PHP 8.1 is using a different git_ref
142+
143+
# PHP 8.1 is overwriting the git_ref
132144
8.1:
145+
type: git
133146
git_ref: v1.0.0
147+
134148
# PHP 8.0 is using a different git_ref dynamically with latest tag found
135149
# See the usage of supported shell code
136150
8.0:
151+
type: git
137152
git_ref: $( git tag | sort -V | tail -1 )
138153
```
139154

@@ -165,12 +180,12 @@ all:
165180

166181
**Note:** All keys that support shell code can be written as a single line yaml definition or as a multi line yaml definition. Multi-line yaml definitions need a trailing `\` at the end of each line, including the last line.<br/>
167182
**Single-line:**
168-
```bash
183+
```yaml
169184
all:
170185
pre: VERSION="$( curl http://url | grep -Eo '[0-9.]+' )"
171186
```
172187
**Multi-line:**
173-
```bash
188+
```yaml
174189
all:
175190
pre: |
176191
VERSION="$( \
@@ -183,7 +198,7 @@ all:
183198

184199
**Note:** All keys that support shell code also support to write multiple shell commands. If you use multiple shell commands, you need to separate them with `&&`.<br/>
185200
**Single-command:**
186-
```bash
201+
```yaml
187202
all:
188203
pre: |
189204
VERSION="$( \
@@ -192,7 +207,7 @@ all:
192207
)" \
193208
```
194209
**Multi-command:**
195-
```bash
210+
```yaml
196211
all:
197212
pre: |
198213
URL="http://url" \

‎doc/contributor/PHP-TOOL-install.yml.md

Lines changed: 216 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -9,3 +9,219 @@ PHP Tools: `install.yml`
99

1010

1111
# Tool definition: `install.yml`
12+
13+
14+
## Top level defines
15+
16+
| Yaml key | Description |
17+
|-----------------|-------------|
18+
| `check` | A check command to test that the tool has been installed correctly. |
19+
| `all` | Is generic for all PHP versions and will be used whenever no specific version is defined. |
20+
| `7.2` | A version specific block for PHP 7.2. Its child keys will overwrite what has been defined in `all`. |
21+
**Example:**
22+
```yaml
23+
check: yq --version 2>&1 | grep -E '[0-9][.0-9]+' || (yq --version; false)
24+
25+
# Default for all PHP version if no overwrite exists
26+
all:
27+
type: pip
28+
version:
29+
build_dep: []
30+
run_dep: []
31+
pre:
32+
post:
33+
34+
35+
# PHP 5.2 is overwriting the version of yq to install
36+
5.2:
37+
type: pip
38+
version: 0.1.0
39+
```
40+
41+
42+
## Second level defines
43+
44+
The following keys can be added below: `all`, `8.2`, `8.1`, `8.0`, `7.4`, ...
45+
46+
| Yaml key | Required | Supports<br/>Shell code | Description |
47+
|-------------|----------|-------------------------|-------------|
48+
| `pre` | No | Yes | Specify a shell command to be run before module installation. |
49+
| `post` | No | Yes | Specify a shell command to be run after module installation. |
50+
| `build_dep` | No | No | Array Debian packages required to build the module (they won't be present in the final image - only used to built the module) If you don't need any, assign it an empty array: `build_dep: []`. |
51+
| `run_dep` | No | No | Array Debian packages required for the module run-time (they won't be present during the build stage - only in the final image). If you don't need any, assign it an empty array: `run_dep: []`. |
52+
| `type` | **Yes** | No | On of the following types to build the module: `apt`, `composer`, `npm`, `pip`, `rubygem` or `custom`. |
53+
54+
**Note:** When using `type: custom`, all data needs to be installed into `/usr/local/bin` as only this directory is copied into the next docker stage during multi-stage build.
55+
56+
57+
## Second level defines for `type: apt`
58+
59+
| Yaml key | Required | Supports<br/>Shell code | Description |
60+
|-------------|----------|-------------------------|-------------|
61+
| `package` | Yes | No | Specify the Debian apt package to install |
62+
63+
**Example:**
64+
```yaml
65+
all:
66+
type: apt
67+
package: netcat
68+
69+
5.3:
70+
type: apt
71+
package: netcat.traditional
72+
```
73+
74+
75+
## Second level defines for `type: composer`
76+
77+
| Yaml key | Required | Supports<br/>Shell code | Description |
78+
|-------------|----------|-------------------------|-------------|
79+
| `package` | Yes | No | Specify the Composer package name to install |
80+
| `composer` | Yes | No | Specify the composer version to use for installation: `1` or `2` |
81+
| `version` | No | Yes | Specify the Composer package version to install |
82+
| `binary` | No | Yes | Specify the composer relative binary path to symlink to `/usr/loca/bin/` |
83+
| `flags` | No | Yes | Add composer flags to `composer require` |
84+
85+
**Example:**
86+
```yaml
87+
all:
88+
type: composer
89+
composer: 2
90+
package: laravel/installer
91+
binary: bin/laravel
92+
93+
7.1:
94+
type: composer
95+
version: 2.3.0
96+
binary: laravel
97+
```
98+
99+
100+
## Second level defines for `type: npm`
101+
102+
| Yaml key | Required | Supports<br/>Shell code | Description |
103+
|-------------|----------|-------------------------|-------------|
104+
| `package` | Yes | No | Specify the NPM package name to install |
105+
| `version` | No | Yes | Specify the NPM package version to install |
106+
| `binary` | No | Yes | Specify the NPM relative binary path to symlink to `/usr/loca/bin/` |
107+
108+
**Example:**
109+
```yaml
110+
all:
111+
type: npm
112+
package: pm2
113+
binary: pm2
114+
version:
115+
```
116+
117+
118+
## Second level defines for `type: pip`
119+
120+
| Yaml key | Required | Supports<br/>Shell code | Description |
121+
|-------------|----------|-------------------------|-------------|
122+
| `version` | No | Yes | Specify the Pip package version to install |
123+
124+
The PyPI package name defaults to the name specified in `options.yml`.
125+
126+
**Example:**
127+
```yaml
128+
all:
129+
type: pip
130+
version:
131+
build_dep: []
132+
run_dep: []
133+
pre:
134+
post: |
135+
ln -s pwncat /usr/local/bin/netcat \
136+
```
137+
138+
139+
## Second level defines for `type: rubygem`
140+
141+
| Yaml key | Required | Supports<br/>Shell code | Description |
142+
|-------------|----------|-------------------------|-------------|
143+
| `package` | Yes | No | Specify the Rubygem package name to install |
144+
| `version` | No | Yes | Specify the Rubygem package version to install |
145+
146+
**Example:**
147+
```yaml
148+
all:
149+
type: rubygem
150+
package: mdl
151+
build_dep: [ruby-dev]
152+
run_dep: [ruby]
153+
154+
7.2:
155+
type: rubygem
156+
version: 0.11.0
157+
pre: |
158+
gem install chef-utils -v 16.6.14 \
159+
```
160+
161+
162+
## Second level defines for `type: custom`
163+
164+
| Yaml key | Required | Supports<br/>Shell code | Description |
165+
|-------------|----------|-------------------------|-------------|
166+
| `command` | Yes | Yes | Custom command to install a tool. |
167+
168+
**Note:** When using `type: custom`, all data needs to be installed into `/usr/local/bin` as only this directory is copied into the next docker stage during multi-stage build.
169+
170+
**Example:**
171+
```yaml
172+
all:
173+
type: custom
174+
command: curl -sS -k -L --fail -L "${PHP_CS_FIXER_URL}" -o /usr/local/bin/php-cs-fixer
175+
pre: PHP_CS_FIXER_URL="https://cs.symfony.com/download/php-cs-fixer-v3.phar"
176+
post: chmod +x /usr/local/bin/php-cs-fixer
177+
178+
7.3:
179+
type: custom
180+
pre: PHP_CS_FIXER_URL="https://cs.symfony.com/download/php-cs-fixer-v2.phar"
181+
```
182+
183+
184+
## Usage of shell code
185+
186+
### Single-line vs Multi-line
187+
188+
**Note:** All keys that support shell code can be written as a single line yaml definition or as a multi line yaml definition. Multi-line yaml definitions need a trailing `\` at the end of each line, including the last line.<br/>
189+
**Single-line:**
190+
```yaml
191+
all:
192+
pre: VERSION="$( curl http://url | grep -Eo '[0-9.]+' )"
193+
```
194+
**Multi-line:**
195+
```yaml
196+
all:
197+
pre: |
198+
VERSION="$( \
199+
curl http://url \
200+
| grep -Eo '[0-9.]+' \
201+
)" \
202+
```
203+
204+
### Single-command vs Multi-command
205+
206+
**Note:** All keys that support shell code also support to write multiple shell commands. If you use multiple shell commands, you need to separate them with `&&`.<br/>
207+
**Single-command:**
208+
```yaml
209+
all:
210+
pre: |
211+
VERSION="$( \
212+
curl http://url \
213+
| grep -Eo '[0-9.]+' \
214+
)" \
215+
```
216+
**Multi-command:**
217+
```yaml
218+
all:
219+
pre: |
220+
URL="http://url" \
221+
&& VERSION="$( \
222+
curl "${URL} \
223+
| grep -Eo '[0-9.]+' \
224+
)" \
225+
&& echo "${VERSION}" \
226+
227+
```

0 commit comments

Comments
 (0)