Recent changes to Command Reference

Command Reference modified by Ingo

Ingo — Wed, 05 Feb 2020 15:57:45 -0000

--- v16
+++ v17
@@ -171,7 +171,7 @@
 RUN apt-get install ...
 ~~~

-## INCLUDE
+## INCLUDE (Draft - not implemented, yet)
 The include command can be used to structure your features into different Wharfiles, which can be reused in different Wharfiles. The syntax is simple, as the only parameter to the command is the path to the include file.

 ~~~sh

Command Reference modified by Ingo

Ingo — Wed, 05 Feb 2020 15:55:56 -0000

--- v15
+++ v16
@@ -125,6 +125,14 @@
 ENV ADDITIONAL_TOOLCHAIN_PACKAGES libstdc++4.9-dev ...
 ~~~

+If you want to execute some commands in the host sysroot, before the toolchain is packed, you can do this by appending this commands to the TOOLCHAIN commad:
+
+~~~sh
+TOOLCHAIN cross-toolchain.tar \
+    apt-get install -y git; \
+    ...
+~~~
+
 # Host commands

 ## RUN HOST

Command Reference modified by Ingo

Ingo — Fri, 31 Aug 2018 22:35:08 -0000

--- v14
+++ v15
@@ -150,7 +150,7 @@
 ~~~

 ## COPY
-Copy acts very similar to ADD the only differenxe is, that this command really only copies files and directories. So also archives are treated as standsrd files, what might be the intention in some cases.
+Copy acts very similar to ADD. The only differenxe is, that this command really only copies files and directories. So also archives are treated as standard files, what might be the intention in some cases.

 # Common Commands

Command Reference modified by Ingo

Ingo — Thu, 01 Mar 2018 21:28:44 -0000

--- v13
+++ v14
@@ -164,4 +164,25 @@
 ~~~

 ## INCLUDE
+The include command can be used to structure your features into different Wharfiles, which can be reused in different Wharfiles. The syntax is simple, as the only parameter to the command is the path to the include file.

+~~~sh
+ENV ESSID mywifi
+ENV PASSWORD mypass
+INCLUDE net/wpa.wha
+INCLUDE bs/rpi.wha
+~~~
+
+The included files are searched locally, and only as fallback from an URL. The search URL can be specified with the command INCLUDE_URL.
+
+~~~sh
+INCLUDE_URL http://forge.codesys.com/...
+INCLUDE bs/rpi.wha
+~~~
+
+The default URL can be set again by calling INCLUDE_URL without a parameter.
+
+~~~sh
+INCLUDE_URL
+INCLUDE bs/rpi.wha
+~~~

Command Reference modified by Ingo

Ingo — Tue, 27 Feb 2018 10:40:50 -0000

--- v12
+++ v13
@@ -131,6 +131,7 @@
 Host commands can be used for virtually every action which don't need to be executed on the target, but where files on the host are involved.

 For example:
+
 * prepare a bootable image of the target root filesystem
 * download an archive and extract only parts of it
 * compile a kernel and add it to the root filesystem

Command Reference modified by Ingo

Ingo — Tue, 27 Feb 2018 10:39:52 -0000

--- v11
+++ v12
@@ -11,18 +11,16 @@
 When you build a system for a foreign architecture, Wharfie uses Qemu to.be able to execute the commands on your x86 host.

 ## FROM
-The from directive refers the starting point of your root filesystem. Before you can execute any command inside of your new root filesystem, you obviously need a basic root filesystem.
-
-This can be obtained from several sources.
+The from directive refers the starting point of your root filesystem. Before you can execute any command inside of your new root filesystem, you obviously need a basic root filesystem. This can be obtained from several sources.

 ### debootstrap
 You just need to specify the architecture and the debian version in the following syntax:
-~~~
+~~~sh
 debian_<architecture>_<version>
 ~~~

 For example:
-~~~
+~~~sh
 FROM debian_armel_stretch
 ~~~

@@ -30,7 +28,7 @@
 You can specify a tar archive. For example, this can be a build artifact from previous build step.

 For example:
-~~~
+~~~sh
 FROM iotbase.tar
 ~~~

@@ -45,7 +43,7 @@
 You can pass options for the different formats, separated from the Url by a pipe symbol.

 For example:
-~~~
+~~~sh
 FROM https://downloads.raspberrypi.org/raspbian_lite_latest|img=p1|format=tar
 ~~~

@@ -59,7 +57,7 @@
 Run gets exactly one argument. This is the command, which should be executed on the targets root filesystem. This command can be multiline.

 For example:
-~~~
+~~~sh
 RUN apt-get install -y psutils \
     openssh-server ...
 ~~~
@@ -70,13 +68,13 @@
 If you want to install a new software on your target image, you most likely want to use apt. To avoid apt and dpkg from requesting inputs from the user, you can pass "-y" to apt-get.

 For example:
-~~~
+~~~sh
 RUN apt-get install -y tzdata
 ~~~

 In case you want to deviate from the default, you might want to use dpkg-reconfigure after the installation.

-~~~
+~~~sh
 RUN echo Antarctica/Mawson > /etc/timezone && dpkg-reconfigure -f noninteractive tzdata
 ~~~

@@ -84,7 +82,7 @@
 An easy, non-interactive way to add a user and set his password is to use the tools "useradd" and "chpasswd".

 This example adds the user "wharfie" with the password "secret":
-~~~
+~~~sh
 RUN useradd -ms /bin/bash wharfie; echo "wharfie:secret" | chpasswd;
 ~~~

@@ -92,7 +90,7 @@
 This command comes from Docker. There it defines the one and only entry point of the docker container. In Wharfie it defines a command that is executed from a systems service unit. So there can be multiple commands, and they are all executed at the end of the boot process.

 For example:
-~~~
+~~~sh
 CMD ['/run.sh']
 ~~~

@@ -100,14 +98,14 @@
 This command is creating an archive with all the license texts of all installed packages. Note, that packages which are installed from 3rd party sources are not included in this archive.

 For example:
-~~~
+~~~sh
 LICENSE all-licenses.tar
 ~~~

 ## SOURCE
 This command is creating an archive with all debian source packages, which are currently installed in the system. Like for the license archive, this archive doesn't contain 3rd party packages.

-~~~
+~~~sh
 SOURCES all-sources.tar
 ~~~

@@ -117,13 +115,13 @@
 It can be simply exported as a tar archive.

 For example:
-~~~
+~~~sh
 TOOLCHAIN cross-toolchain.tar
 ~~~

 If you need more host tools then just the gcc compiler, you can define those packages in an environment variable.

-~~~
+~~~sh
 ENV ADDITIONAL_TOOLCHAIN_PACKAGES libstdc++4.9-dev ...
 ~~~

@@ -146,7 +144,7 @@
 Every archive will be implicitely extracted into the destination folder.

 For example:
-~~~
+~~~sh
 ADD etc.tar /etc
 ~~~

@@ -159,7 +157,7 @@
 With this command, you can set global environment variables, which are accessible in every RUN or RUN HOST command. This includes environment variables of sub processes.

 For example:
-~~~
+~~~sh
 ENV DEBIAN_FRONTEND noninteractive
 RUN apt-get install ...
 ~~~

Command Reference modified by Ingo

Ingo — Tue, 27 Feb 2018 00:37:46 -0000

--- v10
+++ v11
@@ -51,7 +51,7 @@

 The format specifies, where to stop with the extract. In the FROM statement this should always be a tar archive. But when this syntax is used in an ADD statement, you might leave this empty and pass an option like "|tar=etc/fstab" to extract a single file.

-At first it might a bit confusing why the extraction of an image results in a tar archive, but wharfie treats every folder as a tar archive. Thats the way how a folder is passed to another build step, including all permissions, attributes and links.
+At first it might be a bit confusing why the extraction of an image results in a tar archive. But wharfie treats every folder as a tar archive. Thats the way how a folder is passed to another build step, including all permissions, attributes and links.

 The parameter "img=p1" from the example specifies, that we want to extract partition number 1 from the image file. In this case partition number 0 is the boot partition, and number 1 contains the root filesystem.

Command Reference modified by Ingo

Ingo — Tue, 27 Feb 2018 00:35:26 -0000

--- v9
+++ v10
@@ -15,7 +15,7 @@

 This can be obtained from several sources.

-### debootstrap:
+### debootstrap
 You just need to specify the architecture and the debian version in the following syntax:
 ~~~
 debian_<architecture>_<version>

Command Reference modified by Ingo

Ingo — Tue, 27 Feb 2018 00:33:36 -0000

--- v8
+++ v9
@@ -155,7 +155,14 @@

 # Common Commands

-## ENVIRONMENT
+## ENV
+With this command, you can set global environment variables, which are accessible in every RUN or RUN HOST command. This includes environment variables of sub processes.
+
+For example:
+~~~
+ENV DEBIAN_FRONTEND noninteractive
+RUN apt-get install ...
+~~~

 ## INCLUDE

Command Reference modified by Ingo

Ingo — Tue, 27 Feb 2018 00:25:56 -0000

--- v7
+++ v8
@@ -38,10 +38,22 @@
 Beside tar, wharfie supports a few more archive formats, which can be handy to use external sources as a starting point for your image.

 So, the following formats are supported:
-* tar
+* a
 * img
 * zip

+You can pass options for the different formats, separated from the Url by a pipe symbol.
+
+For example:
+~~~
+FROM https://downloads.raspberrypi.org/raspbian_lite_latest|img=p1|format=tar
+~~~
+
+The format specifies, where to stop with the extract. In the FROM statement this should always be a tar archive. But when this syntax is used in an ADD statement, you might leave this empty and pass an option like "|tar=etc/fstab" to extract a single file.
+
+At first it might a bit confusing why the extraction of an image results in a tar archive, but wharfie treats every folder as a tar archive. Thats the way how a folder is passed to another build step, including all permissions, attributes and links.
+
+The parameter "img=p1" from the example specifies, that we want to extract partition number 1 from the image file. In this case partition number 0 is the boot partition, and number 1 contains the root filesystem.

 ##  RUN
 Run gets exactly one argument. This is the command, which should be executed on the targets root filesystem. This command can be multiline.
@@ -131,7 +143,15 @@
 ## ADD
 This action can add files, folders and archives into a root filesystem. Even files and archives from URLs are possible.

+Every archive will be implicitely extracted into the destination folder.
+
+For example:
+~~~
+ADD etc.tar /etc
+~~~
+
 ## COPY
+Copy acts very similar to ADD the only differenxe is, that this command really only copies files and directories. So also archives are treated as standsrd files, what might be the intention in some cases.

 # Common Commands