D Web Development

Chapter 1. Getting Started with Your First Web Application

Today's World Wide Web is shaped by sites, such as Facebook and Amazon, that handle millions of users. The vibe.d framework is designed to create fast and scalable web applications. A significant difference from other frameworks is the use of the D programming language.

In this chapter, you will learn the following:

How to install a D compiler and the DUB package manager
What the prerequisites of the vibe.d framework are
What the project structure and files created by the DUB package manager are
How to create a simple web application How to develop with the D programming language

The D programming language is a general purpose programming language that offers modern convenience, modeling power, and native efficiency with a familiar C-style syntax. If you are new to D, then you should visit http://dlang.org/. This site contains the language definition, references to the standard libraries, downloads for the D compiler, and a lot of other tools.

If you have any questions about D, then visit the web forum at http://forum.dlang.org/.

To develop an application in D, all you need is your favorite text editor and the D compiler. The vibe.d framework is used for web applications. You can find information about vibe.d and the programming documentation at http://vibed.org/. For any questions about vibe.d, you can use the web forum at http://forum.rejectedsoftware.com/groups/rejectedsoftware.vibed/.

The vibe.d framework has some external dependencies, too. It requires the event notification library libevent and the OpenSSL libraries. If you need more information about these libraries, then please visit http://libevent.org/ and https://openssl.org/.

The following section describes how to install the D compiler, package manager DUB, and dependencies on your operating system.

Installing the D compiler and the DUB package manager

The vibe.d framework is written in the D programming language. To get started, you need a D compiler and the DUB package manager. You also need to install openssl and libevent, which are used by vibe.d.

There are three major D compilers available, as follows:

The reference compiler, DMD (http://dlang.org/download.html)
The GNU compiler, GDC (http://gdcproject.org/downloads)
The LLVM-based compiler, LDC (https://github.com/ldc-developers/ldc/releases)

You can use any of these compilers to develop with the vibe.d framework. However, the installation instructions are very different. In this book, only the DMD compiler is used.

A recommended setup is to use the DMD compiler during development and one of the other compilers to produce the final highly optimized binary.

Ubuntu and Debian

The easiest way to install DMD on Ubuntu and Debian is to use the D APT repository provided by Jordi Sayol. The website of this project is located at http://d-apt.sourceforge.net/. The steps to install DMD and DUB are as follows:

Open a terminal and type the following in order to add the repository sources:

$ sudo wget http://master.dl.sourceforge.net/project/d-apt/files/d-apt.list -O /etc/apt/sources.list.d/d-apt.list

Then, you need to update the list of packages:
```
$ sudo apt-get update
```
This command complains that the public key for the d-apt repository could not be verified. The displayed fingerprint is EBCF975E5BA24D5E. Allow an unauthenticated install of d-apt and update the list of packages again:
```
$ sudo apt-get -y --allow-unauthenticated install --reinstall d-apt-keyring
$ sudo apt-get update
```

Now you are ready to install the compiler and the package manager:

$ sudo apt-get install -y dmd-bin
$ sudo apt-get install -y dub

Lastly, you need to install openssl and libevent:

$ sudo apt-get install -y libssl-dev libevent-dev

Fedora

On Fedora, you use the pre-built compiler binary from the dlang.org website. There is no package for the DUB package manager therefore, you must built this tool from the source. Refer to http://dlang.org/download.html and download the Fedora package of the DMD compiler. The available version at the time of writing this book is 2.068.2. You may need to change the version number when a new version of the compiler is released. The instructions are given for Fedora 22 or later. If you use Fedora 21 or earlier, then replace the dnf command with yum. The steps to install the DMD complier are as follows:

To install dmd, type in a terminal:

$ sudo dnf install –y dmd-2.068.2-0.fedora.x86_64.rpm

Install the required openssl and libevent libraries. You also need to install the development package of libcurl that is used to compile dub:
```
$ sudo dnf install –y openssl-devel libevent-devel libcurl-devel
```
After that, go to http://code.dlang.org/download and download source tarball of DUB. The current version number is 0.9.24. Again, you need to change the version number if a newer version is available. To compile and install, just type the following:
```
$ tar xvzf dub-0.9.24.tar.gz
$ cd dub-0.9.24
$ ./build.sh
$ sudo cp bin/dub /usr/local/bin
```

Tip

If you get an error message that you are not in the list of sudoers, then you need to change the type of your user to administrator. Open system settings and click on Users. Click on the Unlock button to unlock the window and change the account type to Administrator. Now you can use the sudo command.

OS X

To install the D compiler and the DUB package manager, you can use the Homebrew package manager (http://brew.sh/):

Open a terminal and first update the formulae:
```
$ brew update
```
Now install the D compiler:
```
$ brew install dmd
```
Next, you will install the DUB package manger:
```
$ brew install dub
```
Lastly, you need to install openssl and libevent:
```
$ brew install openssl libevent
```

Windows

On Windows, you will simply use the pre-built binaries from the dlang.org website. Go to http://dlang.org/download.html and download the Windows EXE file of the DMD compiler. Double-click on the downloaded file in order to start the installer and then follow the instructions on the screen. The D compiler is now ready to use.

DUB is installed in a similar way. Go to http://code.dlang.org/download and download the installer for Windows. Double-click on the downloaded file to start the installer and then follow the instructions on the screen as done previously.

Building from source

You can also build the applications from source. For some systems, (for example, FreeBSD, Solaris x86, and Linux on non-Intel platforms) this is the only way to install the software. The following are the instructions for a Portable Operating System Interface (POSIX) for a Unix system.

At the time when this book was written, the compiler itself was translated from C++ to D. Version 2.068 is the first one that requires a D compiler for bootstrap. Therefore, you need to install version 2.067.1 before you can install the current version of the compiler.

At build time, you need the GNU C/C++ compiler (gcc/g++) and GNU make (gmake). Using another compiler or make tool may work but is not well tested. For Phobos (the D standard library), you need to have libcurl installed. If your distribution does not provide libcurl, then you can find the source and install the instructions at the http://curl.haxx.se/libcurl/ website.

The easiest way to build DMD from source is using the GitHub repository. First, you build version 2.067.1. This creates a D compiler that you will then use to compile the final version that you want to install, as follows:

Change to your working directory. Then, check the sources from GitHub:

$ for i in dmd druntime phobos; do
    git clone https://github.com/D-Programming-Language/$i.git;
  done

Now, check out version 2.067.1, as follows:

$ for i in dmd druntime phobos; do
    (cd $i && git checkout v2.067.1);
  done

Compile the D compiler and install it to /tmp/dmd as shown in the following code. The CPU model (32 bit or 64 bit) is automatically determined by the makefile. If this fails, you can add MODEL=32 (for 32 bit) or MODEL=64 (for 64 bit) to the make command:
```
$ for i in dmd druntime phobos; do
    make -C $i -f posix.mak install INSTALL_DIR=/tmp/dmd
  done
```

Now clean the directories:

$ for i in dmd druntime phobos; do
    make -C $i -f posix.mak clean
  done

Next, check out the version of the compiler that you prefer using. Currently, it is 2.068.2:
```
$ for i in dmd druntime phobos; do
    git checkout v2.068.2
  done
```
Then, you can compile and install the version of the compiler. You need to specify the previously installed compiler. The binary is found in sub-folders specifying the operating system and CPU model, for example, linux/bin64 or freebsd/bin32:
```
$ make -C dmd -f posix.mak HOST_DC=/tmp/dmd/linux/bin64/dmd
  install INSTALL_DIR=~/dmdss
$ make -C druntime -f posix.mak install INSTALL_DIR=~/dmd
$ make -C phobos -f posix.mak install INSTALL_DIR=~/dmd
```
The last step is to add the compiler to your PATH environment variable. The syntax depends on the shell you use. For bash, you run:
```
$ export PATH=~/dmd:$PATH
```

Tip

Building the DMD compiler on Windows differs from these generic instructions as you need the Digital Mars C/C++ compiler. I recommend using the binary download for Windows. You can find detailed build instructions for all supported systems in the wiki at http://wiki.dlang.org/Building_DMD.

The DUB package manager is written in D. Go to http://code.dlang.org/download and download the source code archive. Under the file, change the current directory of your shell to the dub-0.9.24 folder and build the application with the following commands. You may need to replace the current version number 0.9.24 with the version you downloaded.

$ tar xvzf dub-0.9.24.tar.gz
$ cd dub-0.9.24
$ ./build.sh

You'll find the binary in the bin folder. You can add this folder to your PATH variable or copy the file to a standard folder, for example, /usr/local/bin:

$ cp bin/dub /usr/local/bin

Verifying your environment

Before you start coding, it is a good idea to check whether the tools work as expected. Run the following command:

$ dmd

You should see the help text provided by the compiler. The version number should be the same as the version you have downloaded.

On Linux and other POSIX systems, you can also check whether the additional libraries are installed. Run the following command:

$ touch empty.d && dmd -main empty.d -L-lssl -L-levent && ./empty

It should produce no error messages.

An error, most likely, indicates that the libevent library or the OpenSSL library is not installed on your system. You should check the install instructions that are mentioned previously for common systems. If your system is not mentioned, then you should consult the manual of your OS to know how to install additional software. If your OS does not provide these libraries, then you have to install them from source. You can find install instructions and the source archive for libevent at http://libevent.org/. The https://openssl.org/ OpenSSL site provides install instructions and the source archive. You can check your DUB installation simply by running the following command:

$ dub help

This prints the help text from DUB. The version number should be the same as the version that you have downloaded.

Creating your first web application

After you have set up your development environment, you are ready to create your first web application.

Using DUB to set up the project structure

The DUB package manager is used to package and build D applications and libraries. The tool can also be used to create the recommended project structure. You need to provide a folder name for your project and an optional project type. The project type can be minimal, vibe.d, or deimos. The project type determines which folders and files are created by running dub. The minimal project type creates the folders and files for a console application while vibe.d creates a vibe.d server application. The deimos project type is used for bindings to C libraries. (Refer to https://github.com/D-Programming-Deimos for the already available bindings.) If no project type is given, the package manager assumes minimal as the project type.

In a terminal, change your current directory to a folder where your projects should live. Run the following command:

$ dub init hello --type=vibe.d
Successfully created an empty project in '/<your path>/hello'.

This creates a new folder named hello. Let's look into the folder:

A file named dub.sdl was created
The public, source, and views folders were created
The source folder contains a file named app.d

The dub.sdl file is the package description and the app.d file is a sample vibe.d application. The public and views folders are for public and UI related files. Open the dub.sdl file in your editor:

name "hello"
description "A simple vibe.d server application."
copyright "Copyright © 2015, <yourid>"
authors "<yourid>"
dependency "vibe-d" version="~>0.7.23"
versions "VibeDefaultMain"

The file uses a description in Simple Declarative Language (SDLang). SDLang was designed for describing data structures and data types. It is well suited for configuration files and build specification. You can find the language specification at https://sdlang.org/.

In its simplest form, a declaration consists of a name and a value or an attribute. In the preceding dub.sdl file, dependency is a name, "vibe-d" is a value, and the key/value pair version="~>0.7.23" is an attribute. To create a nested data structure, you use { and } to specify the inner data.

It is also possible to specify more than one value or attribute. This creates a list or mapping table.

A name must start with a Unicode letter or an underscore. It can be then followed by zero or more Unicode letters, numbers, underscores, dashes, periods, and dollar signs. The format of the value depends on the data type. The most basic specifications are strings, integer numbers, and booleans: "vibe-d" and `vibe-d` are strings. 123 is a signed 32 bit number and 123L a signed 64 bit number. The possible Boolean values are true and false or on and off. The language specification defines some more data types such as date values. If you need to use these data types, please use the language specification available at the previously mentioned link to look up the exact format.

Note

Prior to DUB version 0.9.24, the package description was specified in a file called dub.json in the JSON format. While JSON support stays available (and is used by many available packages), this book uses the new SDLang format.

The fields in the dub.sdl file have the following meaning:

Name	Description
`name`	The name of the package. It is used to uniquely identify the package. It must only consist of lower case ASCII alpha-numeric characters, '-', and '_'. This field is required.
`description`	A brief description of the package.
`copyright`	The copyright declaration.
`authors`	The authors of the package.
`dependency`	A single dependency. The value specifies the name. Attributes version and path are used to specify the required version and a location in the file system.
`versions`	A list of version identifiers that to be defined during compilation.

There are many more fields available. You can find a complete list at http://code.dlang.org/package-format?lang=sdl.

Our goal is to create a web application with the vibe.d framework. DUB has automatically created a dependency to vibe.d in the package description for us.

Dependencies are specified as "name" version="version-string". The name is the name of the package that we are depending on. This explains why the name must be unique; without a unique name, the package manager would not be able to resolve the dependency.

The version string consists of an operator and the version number. This allows you to restrict the version of the required packages. The possible values are as follows:

Restrict to a certain minor version: "~>2.2.13", equivalent to ">=2.2.13 <2.3.0"
Restrict to a certain major version: "~>2.2", equivalent to ">=2.2.0 <3.0.0"
Require a certain version: "==1.3.0"
Require a minimum version: ">=1.3.0"
Require a version range: ">=1.3.0 <=1.3.4"

The recommended way is to use the "~>" operator. This allows flexible updates and should prevent unexpected code breakages. DUB looks up the available versions of a package in the DUB package registry at http://code.dlang.org/. The developers define the version number in their repository, for example, in GitHub. You can find more information about providing your own DUB packages in Chapter 9, Power your Application with vibe.d Extensions.

Our first application is quite simple. The application uses the main() function provided by vibe.d. This requires passing the VibeDefaultMain version identifier to the compiler. Compiler and linker switches are specified using build settings. The main() function is automatically provided if this version identifier is specified.

The use of compiler and linker switches depends on the operating system, processor architecture, and used compiler. DUB supports this with the platform attribute. The platform attribute contains the predefined platform identifiers that are converted to lower case and separated by dashes. The order of the identifiers is os-architecture-compiler. You can find the complete list in the D language reference at http://dlang.org/version.html#PredefinedVersions. Each part is optional. For example, platform="windows-x86_64-ldc" or platform="dmd".

DUB has created a small application, too. The source of the app.d module is as follows:

import vibe.d;

shared static this()
{
  auto settings = new HTTPServerSettings;
  settings.port = 8080;
  settings.bindAddresses = ["::1", "127.0.0.1"];
  listenHTTP(settings, &hello);

  logInfo("Please open http://127.0.0.1:8080/ in your browser.");
}

void hello(HTTPServerRequest req, HTTPServerResponse res)
{
  res.writeBody("Hello, World!");
}

The functionality is quite simple. As the main() function is provided by the framework, a shared static this() module constructor is used. This constructor is run at application startup before the main() function is run. In the constructor, a new HTTPServerSettings object is created. In the following two lines, the port number is set to 8080 and the IP address that the server listens to is set to localhost (IPv4: 127.0.0.1, IPv6: ::1). After that, the HTTP server is started with a call to listenHTTP(). Each request is handled by the hello() function, which only writes the string "Hello, world!" as the response.

You simply run dub in the hello folder in order to compile and run the application. DUB automatically resolves, downloads, and compiles all specified dependencies. Some of the downloaded libraries are only D bindings to the already installed libraries. For example, DUB downloads the D bindings for the OpenSSL library, which must be installed separately. If you run DUB for the first time, the tool fetches all dependencies which looks like this:

$ dub
Fetching memutils 0.4.1 (getting selected version)...
Placing memutils 0.4.1 to /home/<yourid>/.dub/packages/...
Fetching vibe-d 0.7.25 (getting selected version)...
Placing vibe-d 0.7.25 to /home/<yourid>/.dub/packages/...
Fetching libevent 2.0.1+2.0.16 (getting selected version)...
Placing libevent 2.0.1+2.0.16 to /home/<yourid>/.dub/packages/...
Fetching openssl 1.1.4+1.0.1g (getting selected version)...
Placing openssl 1.1.4+1.0.1g to /home/<yourid>/.dub/packages/...
Fetching libev 5.0.0+4.04 (getting selected version)...
Placing libev 5.0.0+4.04 to /home/<yourid>/.dub/packages/...
Fetching libasync 0.7.5 (getting selected version)...
Placing libasync 0.7.5 to /home/<yourid>/.dub/packages/...
Performing "debug" build using dmd for x86_64.
vibe-d 0.7.25: building configuration "libevent"...
hello ~master: building configuration "application"...
Linking...
Running ./hello 
Listening for HTTP requests on ::1:8080
Listening for HTTP requests on 127.0.0.1:8080
Please open http://127.0.0.1:8080/ in your browser.

Open your browser and type http://127.0.0.1:8080/ as address. You see a nice greeting from your first vibe.d application:

Tip

Downloading the example code

You can download the example code files from your account at http://www.packtpub.com for all the Packt Publishing books you have purchased. If you purchased this book elsewhere, you can visit http://www.packtpub.com/support and register to have the files e-mailed directly to you.

Creating your first template

The sample application that is generated by DUB returns only a text string to the browser. Of course, a real web application returns HTML 5 nowadays!

The vibe.d framework includes a template engine, the so-called Diet templates. Templates are used to construct an HTML page from various reusable pieces, for example, a header and navigation bar. They also enable you to place values that are calculated in your application in the generated HTML page. You can learn about the details of templates in Chapter 2, Using Templates for Your Web Pages. For the first application, you create a template for a simple HTML 5 page.

Run dub again to create a new project:

$ dub init hello2 --type=vibe.d
Successfully created an empty project in '/<your path>/hello2'.

You can put UI related files, such as HTML pages and templates, in the views folder. Create an index.dt file in the views folder:

doctype html
html
  head
    title Greetings from vibe.d
  body
    p Hello, World!

The template syntax resembles the HTML syntax and should be understandable if you know HTML. This is a so-called static template since there are no dynamic parts involved, for example, printing the value of a variable.

Next, you need to change the generated source/app.d application to contain the following source:

import vibe.d;

shared static this()
{
  auto settings = new HTTPServerSettings;
  settings.port = 8080;
  settings.bindAddresses = ["::1", "127.0.0.1"];
  listenHTTP(settings, staticTemplate!"index.dt");

  logInfo("Please open http://127.0.0.1:8080/ in your browser.");
}

In the listenHTTP() call, replace &hello with staticTemplate!"index.dt". After that, delete the hello() function. This is all you need to do in order to use a static template!

Run dub to compile and run the application:

$ dub
Compiling diet template 'index.dt'...
 x86_64.
vibe-d 0.7.25: target for configuration "libevent" is up to date.
hello2 ~master: building configuration "application"...
Linking...
To force a rebuild of up-to-date targets, run again with --force.
Running ./hello2 
Listening for HTTP requests on ::1:8080
Listening for HTTP requests on 127.0.0.1:8080
Please open http://127.0.0.1:8080/ in your browser.

Open your browser and type http://127.0.0.1:8080/ in the address bar. You will see a similar greeting as that from your first vibe.d application. Please note that now there is a title displayed. You should also check whether the browser has received an HTML page—simply inspect the page source using facility from your favorite browser.

You may have noticed that this run of DUB was a bit faster and the output was different. The main functionality offered by DUB is the automatic resolution of dependencies. Our application lists vibe.d as a dependency. On the first run, DUB automatically downloads vibe.d. In order to find the package, DUB uses the public registry at http://code.dlang.org/. (There are many useful packages available. You will learn about the most important ones in Chapter 9, Power your Application with vibe.d Extensions. For now, just scroll through the list to get an impression of what is already available.)

The vibe.d framework itself has dependencies. DUB downloads them until all dependencies are resolved. After this step, the libraries and your application are compiled.

On every subsequent invocation of DUB, the dependencies are already resolved and the libraries are only linked with, and no longer have to be compiled. The second invocation is, therefore, faster and produces less output.

You can find the downloaded packages in your home directory in the ${HOME}/.dub/packages hidden folder on Linux or %HOMEDRIVE%%HOMEPATH%\AppData\Roaming\dub on Windows. If you delete the folder or one of the packages inside, then DUB will re-download and recompile the missing packages on the next invocation. Most importantly, you will find the vibe.d package including its source code in this folder!

DUB provides some useful options. You can see them if you pass the --help flag after the run command (the default command that is invoked if no command is given):

$ dub run --help

Two options are very useful: --force and --verbose. With --force, you can force a recompilation even if nothing has changed. The --verbose option prints diagnostic output. This can be helpful if you need to track down an error.

D Web Development: Leverage the power of D and the vibe.d framework to develop web applications that are incredibly fast

What do you get with eBook?

Product Details