diff options
Diffstat (limited to 'guide/getting_started.md')
| -rw-r--r-- | guide/getting_started.md | 312 |
1 files changed, 0 insertions, 312 deletions
diff --git a/guide/getting_started.md b/guide/getting_started.md deleted file mode 100644 index a5f811d..0000000 --- a/guide/getting_started.md +++ /dev/null @@ -1,312 +0,0 @@ -Getting started -=============== - -Erlang is more than a language, it is also an operating system -for your applications. Erlang developers rarely write standalone -modules, they write libraries or applications, and then bundle -those into what is called a release. A release contains the -Erlang VM plus all applications required to run the node, so -it can be pushed to production directly. - -This chapter walks you through all the steps of setting up -Cowboy, writing your first application and generating your first -release. At the end of this chapter you should know everything -you need to push your first Cowboy application to production. - -Application skeleton --------------------- - -Let's start by creating this application. We will simply call it -`hello_erlang`. This application will have the following directory -structure: - -``` -hello_erlang/ - src/ - hello_erlang.app.src - hello_erlang_app.erl - hello_erlang_sup.erl - hello_handler.erl - erlang.mk - Makefile - relx.config -``` - -Once the release is generated, we will also have the following -files added: - -``` -hello_erlang/ - ebin/ - hello_erlang.app - hello_erlang_app.beam - hello_erlang_sup.beam - hello_handler.beam - _rel/ - relx -``` - -As you can probably guess, the `.app.src` file end up becoming -the `.app` file, and the `.erl` files are compiled into `.beam`. -Then, the whole release will be copied into the `_rel/` directory. - -The `.app` file contains various informations about the application. -It contains its name, a description, a version, a list of modules, -default configuration and more. - -Using a build system like [erlang.mk](https://github.com/extend/erlang.mk), -the list of modules will be included automatically in the `.app` file, -so you don't need to manually put them in your `.app.src` file. - -For generating the release, we will use [relx](https://github.com/erlware/relx) -as it is a much simpler alternative to the tool coming with Erlang. - -First, create the `hello_erlang` directory. It should have the same name -as the application within it. Then we create the `src` directory inside -it, which will contain the source code for our application. - -``` bash -$ mkdir hello_erlang -$ cd hello_erlang -$ mkdir src -``` - -Let's first create the `hello_erlang.app.src` file. It should be pretty -straightforward for the most part. You can use the following template -and change what you like in it. - -``` erlang -{application, hello_erlang, [ - {description, "Hello world with Cowboy!"}, - {vsn, "0.1.0"}, - {modules, []}, - {registered, [hello_erlang_sup]}, - {applications, [ - kernel, - stdlib, - cowboy - ]}, - {mod, {hello_erlang_app, []}}, - {env, []} -]}. -``` - -The `modules` line will be replaced with the list of modules during -compilation. Make sure to leave this line even if you do not use it -directly. - -The `registered` value indicates which processes are registered by this -application. You will often only register the top-level supervisor -of the application. - -The `applications` value lists the applications that must be started -for this application to work. The Erlang release will start all the -applications listed here automatically. - -The `mod` value defines how the application should be started. Erlang -will use the `hello_erlang_app` module for starting the application. - -The `hello_erlang_app` module is what we call an application behavior. -The application behavior must define two functions: `start/2` and -`stop/1`, for starting and stopping the application. A typical -application module would look like this: - -``` erlang --module(hello_erlang_app). --behavior(application). - --export([start/2]). --export([stop/1]). - -start(_Type, _Args) -> - hello_erlang_sup:start_link(). - -stop(_State) -> - ok. -``` - -That's not enough however. Since we are building a Cowboy based -application, we also need to initialize Cowboy when we start our -application. - -Setting up Cowboy ------------------ - -Cowboy does nothing by default. - -Cowboy uses Ranch for handling the connections and provides convenience -functions to start Ranch listeners. - -The `cowboy:start_http/4` function starts a listener for HTTP connections -using the TCP transport. The `cowboy:start_https/4` function starts a -listener for HTTPS connections using the SSL transport. - -Listeners are a group of processes that are used to accept and manage -connections. The processes used specifically for accepting connections -are called acceptors. The number of acceptor processes is unrelated to -the maximum number of connections Cowboy can handle. Please refer to -the [Ranch guide](http://ninenines.eu/docs/en/ranch/HEAD/guide/) -for in-depth information. - -Listeners are named. They spawn a given number of acceptors, listen for -connections using the given transport options and pass along the protocol -options to the connection processes. The protocol options must include -the dispatch list for routing requests to handlers. - -The dispatch list is explained in greater details in the -[Routing](routing.md) chapter. For the purpose of this example -we will simply map all URLs to our handler `hello_handler`, -using the wildcard `_` for both the hostname and path parts -of the URL. - -This is what the `hello_erlang_app:start/2` function looks like -with Cowboy initialized. - -``` erlang -start(_Type, _Args) -> - Dispatch = cowboy_router:compile([ - %% {URIHost, list({URIPath, Handler, Opts})} - {'_', [{'_', hello_handler, []}]} - ]), - %% Name, NbAcceptors, TransOpts, ProtoOpts - cowboy:start_http(my_http_listener, 100, - [{port, 8080}], - [{env, [{dispatch, Dispatch}]}] - ), - hello_erlang_sup:start_link(). -``` - -Do note that we told Cowboy to start listening on port 8080. -You can change this value if needed. - -Our application doesn't need to start any process, as Cowboy -will automatically start processes for every incoming -connections. We are still required to have a top-level supervisor -however, albeit a fairly small one. - -``` erlang --module(hello_erlang_sup). --behavior(supervisor). - --export([start_link/0]). --export([init/1]). - -start_link() -> - supervisor:start_link({local, ?MODULE}, ?MODULE, []). - -init([]) -> - {ok, {{one_for_one, 10, 10}, []}}. -``` - -Finally, we need to write the code for handling incoming requests. - -Handling HTTP requests ----------------------- - -Cowboy features many kinds of handlers. For this simple example, -we will just use the plain HTTP handler, which has three callback -functions: `init/3`, `handle/2` and `terminate/3`. You can find more -information about the arguments and possible return values of these -callbacks in the -[cowboy_http_handler function reference](http://ninenines.eu/docs/en/cowboy/HEAD/manual/cowboy_http_handler). - -Our handler will only send a friendly hello back to the client. - -``` erlang --module(hello_handler). --behavior(cowboy_http_handler). - --export([init/3]). --export([handle/2]). --export([terminate/3]). - -init(_Type, Req, _Opts) -> - {ok, Req, undefined_state}. - -handle(Req, State) -> - {ok, Req2} = cowboy_req:reply(200, [ - {<<"content-type">>, <<"text/plain">>} - ], <<"Hello World!">>, Req), - {ok, Req2, State}. - -terminate(_Reason, _Req, _State) -> - ok. -``` - -The `Req` variable above is the Req object, which allows the developer -to obtain information about the request and to perform a reply. -Its usage is documented in the -[cowboy_req function reference](http://ninenines.eu/docs/en/cowboy/HEAD/manual/cowboy_req). - -The code for our application is ready, so let's build a release! - -Compiling ---------- - -First we need to download `erlang.mk`. - -``` bash -$ wget https://raw.github.com/extend/erlang.mk/master/erlang.mk -$ ls -src/ -erlang.mk -``` - -Then we need to create a Makefile that will include `erlang.mk` -for building our application. We need to define the Cowboy -dependency in the Makefile. Thankfully `erlang.mk` already -knows where to find Cowboy as it features a package index, -so we can just tell it to look there. - -``` Makefile -PROJECT = hello_erlang - -DEPS = cowboy -dep_cowboy = pkg://cowboy master - -include erlang.mk -``` - -Note that when creating production nodes you will most likely -want to use a specific version of Cowboy instead of `master`, -and properly test your release every time you update Cowboy. - -If you type `make` in a shell now, your application should build -as expected. If you get compilation errors, double check that you -haven't made any typo when creating the previous files. - -``` bash -$ make -``` - -Generating the release ----------------------- - -That's not all however, as we want to create a working release. -For that purpose, we need to create a `relx.config` file. When -this file exists, `erlang.mk` will automatically download `relx` -and build the release when you type `make`. - -In the `relx.config` file, we only need to tell `relx` that -we want the release to include the `hello_erlang` application, -and that we want an extended start script for convenience. -`relx` will figure out which other applications are required -by looking into the `.app` files for dependencies. - -``` erlang -{release, {hello_erlang, "1"}, [hello_erlang]}. -{extended_start_script, true}. -``` - -The `release` value is used to specify the release name, its -version, and the applications to be included. - -We can now build and start the release. - -``` bash -$ make -$ ./_rel/hello_erlang/bin/hello_erlang console -``` - -If you then access `http://localhost:8080` using your browser, -you should receive a nice greet! |