Merge pull request #435 from Drup/instructions

Update the instructions to build the website.

.gitignore

@@ -9,6 +9,8 @@
 /src/mir-main
 /src/main.native
 /src/www.xl
+/src/www.xl.in
+/src/key_gen.ml
 /src/www.xe
 /src/www_libvirt.xml
 
@@ -22,8 +24,7 @@
 /src/static[0-9].ml
 /src/static[0-9].mli
 /src/fat*.img
-/src/make-fat1-image.sh
-/src/make-fat2-image.sh
+/src/make-fat*.sh
 
 files/js/stats
 

Makefile

@@ -16,50 +16,25 @@
 # PERFORMANCE OF THIS SOFTWARE.
 #
 
-# MODE: unix for Unix executable, xen for Xen unikernel
-MODE   ?= unix
-# FS: crunch for in-memory read-only store, fat for read-write filesystem
-FS     ?= crunch
-# NET: direct for mirage network stack, socket for unix sockets (Unix mode only)
-NET    ?= direct
 # XENIMG: the name to provide for the xen image and configuration
 XENIMG ?= www
-# HOST: all links will be relative to this domain; default is localhost
-HOST   ?= localhost
-
-# to configure the network via DHCP:
-# DHCP = true
-
-# to configure the network statically with ip 10.0.0.2/24 and gateway 10.0.0.1:
-# IP = "10.0.0.2"
-# NETMASK = "255.255.255.0"
-# GATEWAYS = "10.0.0.1"
-#
-# if none of DHCP || (IP && NETMASK && GATEWAYS) is set,
-# default static settings will be used.
-
-# to serve pages over https:
-# TLS = true
-# to make it work with FS=crunch, put the certificate in tls/tls/server.key and the private key in tls/tls/server.pem
-
-# to redirect all http requests to https://somewhereelse.org:
-# REDIRECT = https://somewhereelse.org
-# (redirect must be an http:// or https:// url)
-# if TLS is set but REDIRECT is not, the value of REDIRECT will be assumed to be https://$HOST , with the effect that all http requests will be redirected to https
 
+# FLAGS for the "mirage configure" command.
 FLAGS  ?=
 
 .PHONY: all configure build run clean
 
 all:
-	@echo "To build this website, look in the Makefile and set"
-	@echo "the appropriate variables (MODE, FS, NET, DHCP, REDIRECT, HOST, TLS)."
-	@echo "make configure && make depend && make build"
+	@echo "To build this website, first use \"make prepare\""
+	@echo "You can then build the mirage application in the src/ directory"
+	@echo "cd src && mirage configure && make"
+	@echo "For unikernel configuration option, do \"mirage configure --help\" in src/"
 
-configure:
+prepare:
 	cd stats && make depend
-	# the make depend in src will crunch the stats into the fs:
 	cd stats && make all
+
+configure: prepare
 	mirage configure -f src/config.ml $(FLAGS) -t $(MODE)
 
 depend:

README.md

@@ -8,6 +8,15 @@ It provides information about the project as well as the blog and wiki.
 
 It also serves as a good first self-hosting test case.
 
+
+To build this website, first use `make prepare`
+You can then build the mirage application in the src/ directory:
+```
+cd src && mirage configure && make
+```
+
+For unikernel configuration options, use `mirage configure --help` in `src`.
+
 To update, send a pull request. When successfully merged, the Travis CI scripts,
 fetched from <https://github.com/ocaml/ocaml-travisci-skeleton/>, will cause the
 generated Xen unikernel to be committed back to the

src/config.ml

@@ -26,8 +26,8 @@ open Mirage
 
 let tls_key =
   let doc = Key.Arg.info
-      ~doc:"Enable serving the website over https."
-      ~env:"TLS" ["tls"]
+      ~doc:"Enable serving the website over https. Do not forget to put certificates in tls/"
+      ~docv:"BOOL" ~env:"TLS" ["tls"]
   in
   Key.(create "tls" Arg.(opt ~stage:`Configure bool false doc))
 
@@ -42,14 +42,15 @@ let pr_key =
 let host_key =
   let doc = Key.Arg.info
       ~doc:"Hostname of the unikernel."
-      ~env:"HOST" ["host"]
+      ~docv:"URL" ~env:"HOST" ["host"]
   in
   Key.(create "host" Arg.(opt string "localhost" doc))
 
 let redirect_key =
   let doc = Key.Arg.info
-      ~doc:"Where to redirect to."
-      ~env:"REDIRECT" ["redirect"]
+      ~doc:"Where to redirect to. Must start with http:// or https://. \
+            When tls is enabled, the default is https://$HOST, with the effect that all http requests will be redirected to https"
+      ~docv:"URL" ~env:"REDIRECT" ["redirect"]
   in
   Key.(create "redirect" Arg.(opt (some string) None doc))
 

tmpl/wiki/hello-world.md

@@ -286,9 +286,10 @@ open Mirage
 
 let main = foreign "Unikernel.Main" (console @-> block @-> job)
 
-let img = match get_mode () with
-  | `Xen -> block_of_file "xvda1"
-  | `Unix | `MacOSX -> block_of_file "disk.img"
+let img =
+  if_impl Key.is_xen
+    (block_of_file "xvda1")
+    (block_of_file "disk.img")
 
 let () =
   register "block_test" [main $ default_console $ img]
@@ -571,21 +572,7 @@ of this selection logic is simple enough.
 ```
 open Mirage
 
-let mode =
-  let x = try Unix.getenv "FS" with Not_found -> "crunch" in
-  match x with
-  | "fat"    -> `Fat
-  | "crunch" -> `Crunch
-  | x        -> failwith ("Unknown FS mode: " ^ x)
-
-let fat_ro dir =
-  kv_ro_of_fs (fat_of_files ~dir ())
-
-let disk =
-  match mode, get_mode () with
-  | `Fat   , _                 -> fat_ro "t"
-  | `Crunch, `Xen              -> crunch "t"
-  | `Crunch, (`Unix | `MacOSX) -> direct_kv_ro "t"
+let disk = generic_kv_ro "t"
 
 let main =
   foreign "Unikernel.Main" (console @-> kv_ro @-> kv_ro @-> job)
@@ -601,7 +588,7 @@ appropriate settings for external filesystem access.
 On OSX:
 
 ```
-$ env FS=fat mirage configure --unix
+$ mirage configure --unix --kv_ro fat
 $ ./make-fat1-image.sh
 $ file fat1.img
 fat1.img: x86 boot sector, code offset 0x0, OEM-ID "ocamlfat",
@@ -612,7 +599,7 @@ sectors/FAT 1, sectors 49 (volumes > 32 MB) , dos < 4.0 BootSector (0x0)
 or, on Linux:
 
 ```
-$ env FS=fat mirage configure --unix
+$ mirage configure --unix --kv_ro fat
 $ ./make-fat1-image.sh
 $ file fat1.img
 fat1.img: x86 boot sector
@@ -661,29 +648,12 @@ directory in `mirage-skeleton`.
 ```
 open Mirage
 
-let net =
-  try match Sys.getenv "NET" with
-    | "direct" -> `Direct
-    | "socket" -> `Socket
-    | _        -> `Direct
-  with Not_found -> `Direct
-
-let dhcp =
-  try match Sys.getenv "DHCP" with
-    | "" -> false
-    | _  -> true
-  with Not_found -> false
-
-let stack =
-  match net, dhcp with
-  | `Direct, true  -> direct_stackv4_with_dhcp default_console tap0
-  | `Direct, false -> direct_stackv4_with_default_ipv4 default_console tap0
-  | `Socket, _     -> socket_stackv4 default_console [Ipaddr.V4.any]
+let handler = foreign "Unikernel.Main" (console @-> stackv4 @-> job)
 
-let main = foreign "Unikernel.Main" (console @-> stackv4 @-> job)
+let stack = generic_stackv4 default_console tap0
 
 let () =
-  register "stackv4" [main $ default_console $ stack]
+  register "stackv4" [handler $ default_console $ stack]
 ```
 
 This configuration shows how composable the network stack subsystem is: the
@@ -726,7 +696,7 @@ first.
 
 ```
 $ cd stackv4
-$ env NET=socket mirage configure --unix
+$ mirage configure --unix --net socket
 $ make
 $ sudo ./mir-stackv4
 Manager: connect
@@ -767,7 +737,7 @@ Assuming you've got a DHCP server running:
 
 ```
 $ cd stackv4
-$ env NET=direct DHCP=true mirage configure --unix
+$ mirage configure --unix --dhcp true --net direct
 $ make
 $ sudo ./mir-stackv4
 Netif: connect unknown
@@ -837,7 +807,7 @@ ensure we have a route to it. Thus:
 
 ```
 $ cd stackv4
-$ env NET=direct DHCP=false mirage configure --unix
+$ mirage configure --unix --dhcp false --net direct
 $ make
 $ sudo ./mir-stackv4
 Netif: plugging into tap0 with mac c2:9d:56:19:d7:2c
@@ -905,7 +875,7 @@ configuration file already disables the socket-based job if a Xen compilation is
 detected, leaving just the OCaml TCP/IP stack.
 
 ```
-$ env DHCP=true mirage configure --xen
+$ mirage configure --xen --dhcp true
 $ make
 ```
 

tmpl/wiki/mirage-www.md

@@ -20,42 +20,18 @@ step by step.
 
 ## Building a Unix version
 
-The `src/config.ml` takes its configuration variables from some environment
-variables, which can be supplied manually or provided via the `Makefile`:
-
-```
-MODE   ?= unix
-FS     ?= crunch
-NET    ?= direct
-XENIMG ?= www
-HOST   ?= localhost
-```
-
-These `Makefile` variables do the following:
-* `MODE` is either `unix` or `xen`, selecting the backend you're compiling for.
-* `FS` is either `fat` or `crunch`, depending on if you want to use an external
-  block device or simply compile the website contents directly into the `mirage`
-  binary.
-* `NET` is either `socket` or `direct`, selecting whether you wish to use the
-  host-local network stack, or the MirageOS network stack respectively. Note
-  that building for `MODE=xen` implies `NET=direct`.
-* `XENIMG` sets the name of the built Xen VM image and configuration.
-* `HOST` sets the root domain for the site, to which links are relative.
-
-To configure the network, the following further variables can be set:
-+ `DHCP` is either `false` (or blank) or `true`, specifying whether the
-  unikernel should acquire address information via DHCP on startup.
-+ (`IP`,`NETMASK`,`GATEWAYS`) indicate static IP configuration and should be set
-  to the desired IP address, the netmask and a `:`-separated list of gateways.
-+ `TLS` is either `false` or `true` (default: `false`).
-+ `REDIRECT` is set to the `https` target for all `http` requests. If `TLS` is
-  set but `REDIRECT` is not, then `REDIRECT=https://$HOST` is assumed.
-
-If neither `DHCP` nor all of `IP`, `NETMASK` and `GATEWAYS` are set, then
-`IP="10.0.0.2"`, `NETMASK="255.255.255.0"` and `GATEWAYS="10.0.0.1"` are
-assumed. This can be overridden by editing the `config.ml` (see the
-[live website configuration](https://github.com/mirage/mirage-www/blob/master/.travis.yml)
-for an example of a static IPv4 address).
+In order to configure the unikernel, we can use the mirage tool. To see all the available options:
+
+```
+cd src
+mirage configure --help
+```
+
+Alternatively, You can get a quick overview of all the options (and their current value):
+
+```
+mirage describe
+```
 
 ### A Unix development workflow
 
@@ -69,34 +45,24 @@ First, if you wish to build the site to present the site statistics (garbage
 collection, etc) data, build the JavaScript:
 
 ```
-cd stats && make depend build
+make prepare
 ```
 
 Then configure and build the website itself:
 
 ```
 $ cd src
-$ env NET=socket FS=crunch mirage configure --unix
+$ mirage configure --unix --kv_ro crunch --net socket
 $ make
 ```
 
-Alternatively you can use the toplevel `Makefile` to achieve both the above
-steps:
-
-```
-$ make NET=socket FS=crunch configure
-$ make build
-```
-
 Finally, run the website application:
 
 ```
 $ sudo ./mir-www
 ```
 
-For the rest of the tutorial, we'll call `mirage` directly rather than use the
-`Makefile`, as this makes the tools usage clearer. If you run the above
-commands, the website will now be available on `http://localhost/`.
+The website will now be available on `http://localhost/`.
 
 ## Building the direct networking version
 
@@ -107,7 +73,7 @@ On Unix with a tuntap device:
 
 ```
 $ cd src
-$ env NET=direct mirage configure --unix
+$ mirage configure --unix --net direct
 $ make
 $ sudo ./mir-www
 ```
@@ -143,26 +109,26 @@ variables, so we can quickly try it as follows.
 
 ```
 $ cd src
-$ env FS=fat mirage configure --unix
+$ mirage configure --unix --kv_ro fat
 $ make
 $ sudo ./mir-www & sudo ifconfig tap0 10.0.0.1 255.255.255.0 && fg
 ```
 
-The `make-fat-images.sh` script uses the `fat` command-line helper installed by
+The `make-fat_*-images.sh` script uses the `fat` command-line helper installed by
 the `ocaml-fat` package to build the FAT block image for you. If you now access
 the website, it is serving the traffic straight from the FAT image you just
 created, without requiring a Unix filesystem at all!
 
 You can inspect the resulting FAT images for yourself by using the `fat` command
-line tool, and the `make-fat1-image.sh` script.
+line tool, and the generated scripts.
 
 ```
-$ file fat1.img
+$ file fat_block1.img
 fat1.img: x86 boot sector, code offset 0x0, OEM-ID "ocamlfat",
 sectors/cluster 4, FAT  1, root entries 512, Media descriptor 0xf8,
 sectors/FAT 2, sectors 1728 (volumes > 32 MB) , dos < 4.0 BootSector (0x0)
 
-$ fat list fat1.img
+$ fat list fat_block1.img
 /wiki (DIR)(1856 bytes)
 /wiki/xen-synthesize-virtual-disk.md (FILE)(8082 bytes)
 /wiki/xen-suspend.md (FILE)(14120 bytes)