From b051513f18653113ac2c23008836c500e1425283 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Lo=C3=AFc=20Hoguin?= Date: Sat, 5 Nov 2016 14:26:30 +0200 Subject: Update docs --- .../en/cowboy/2.0/manual/cowboy.set_env/index.html | 2 +- docs/en/cowboy/2.0/manual/cowboy/index.html | 6 +- .../cowboy/2.0/manual/cowboy_req.header/index.html | 258 ++++ .../2.0/manual/cowboy_req.headers/index.html | 228 ++++ .../cowboy/2.0/manual/cowboy_req.host/index.html | 229 ++++ .../cowboy/2.0/manual/cowboy_req.method/index.html | 238 ++++ .../cowboy/2.0/manual/cowboy_req.path/index.html | 228 ++++ .../cowboy/2.0/manual/cowboy_req.peer/index.html | 234 ++++ .../cowboy/2.0/manual/cowboy_req.port/index.html | 228 ++++ docs/en/cowboy/2.0/manual/cowboy_req.qs/index.html | 227 ++++ .../cowboy/2.0/manual/cowboy_req.scheme/index.html | 227 ++++ .../en/cowboy/2.0/manual/cowboy_req.uri/index.html | 315 +++++ .../2.0/manual/cowboy_req.version/index.html | 226 ++++ docs/en/cowboy/2.0/manual/cowboy_req/index.html | 1374 ++++---------------- docs/en/cowboy/2.0/manual/index.html | 55 + docs/en/erlang.mk/1/guide/app.asciidoc | 7 + docs/en/erlang.mk/1/guide/app/index.html | 19 + docs/en/erlang.mk/1/guide/deps.asciidoc | 49 + docs/en/erlang.mk/1/guide/deps/index.html | 54 + docs/en/erlang.mk/1/guide/escripts.asciidoc | 81 +- docs/en/erlang.mk/1/guide/escripts/index.html | 90 +- .../1/guide/external_plugins_list.asciidoc | 9 +- .../1/guide/external_plugins_list/index.html | 11 +- docs/en/erlang.mk/1/guide/getting_started.asciidoc | 4 +- .../erlang.mk/1/guide/getting_started/index.html | 4 +- docs/en/erlang.mk/1/guide/index.html | 5 + docs/en/erlang.mk/1/guide/installation.asciidoc | 51 +- docs/en/erlang.mk/1/guide/installation/index.html | 58 +- docs/en/erlang.mk/1/guide/releases.asciidoc | 54 +- docs/en/erlang.mk/1/guide/releases/index.html | 59 +- docs/en/erlang.mk/1/guide/sfx.asciidoc | 49 + docs/en/erlang.mk/1/guide/sfx/index.html | 206 +++ docs/en/ranch/1.2/manual/ranch_ssl/index.html | 27 + docs/index.xml | 68 +- donate/index.html | 24 + index.html | 24 + services/index.html | 24 + sitemap.xml | 80 +- 38 files changed, 3931 insertions(+), 1201 deletions(-) create mode 100644 docs/en/cowboy/2.0/manual/cowboy_req.header/index.html create mode 100644 docs/en/cowboy/2.0/manual/cowboy_req.headers/index.html create mode 100644 docs/en/cowboy/2.0/manual/cowboy_req.host/index.html create mode 100644 docs/en/cowboy/2.0/manual/cowboy_req.method/index.html create mode 100644 docs/en/cowboy/2.0/manual/cowboy_req.path/index.html create mode 100644 docs/en/cowboy/2.0/manual/cowboy_req.peer/index.html create mode 100644 docs/en/cowboy/2.0/manual/cowboy_req.port/index.html create mode 100644 docs/en/cowboy/2.0/manual/cowboy_req.qs/index.html create mode 100644 docs/en/cowboy/2.0/manual/cowboy_req.scheme/index.html create mode 100644 docs/en/cowboy/2.0/manual/cowboy_req.uri/index.html create mode 100644 docs/en/cowboy/2.0/manual/cowboy_req.version/index.html create mode 100644 docs/en/erlang.mk/1/guide/sfx.asciidoc create mode 100644 docs/en/erlang.mk/1/guide/sfx/index.html diff --git a/docs/en/cowboy/2.0/manual/cowboy.set_env/index.html b/docs/en/cowboy/2.0/manual/cowboy.set_env/index.html index bce57e3c..ea6c5a1c 100644 --- a/docs/en/cowboy/2.0/manual/cowboy.set_env/index.html +++ b/docs/en/cowboy/2.0/manual/cowboy.set_env/index.html @@ -127,9 +127,9 @@ Value

The new value.

The type of the value differs depending on the key.

diff --git a/docs/en/cowboy/2.0/manual/cowboy/index.html b/docs/en/cowboy/2.0/manual/cowboy/index.html index a6aba962..2d8b5978 100644 --- a/docs/en/cowboy/2.0/manual/cowboy/index.html +++ b/docs/en/cowboy/2.0/manual/cowboy/index.html @@ -123,10 +123,10 @@ http://www.gnu.org/software/src-highlite --> | {Name, Constraints} | {Name, Constraints, Default}] -Name :: atom() +Name :: atom() Constraints :: Constraint | [Constraint] -Constraint :: cowboy_constraints:constraint() -Default :: any()

+Constraint :: cowboy_constraints:constraint() +Default :: any()

Fields description for match operations.

This type is used in cowboy_router(3) for matching bindings and in the match functions found in diff --git a/docs/en/cowboy/2.0/manual/cowboy_req.header/index.html b/docs/en/cowboy/2.0/manual/cowboy_req.header/index.html new file mode 100644 index 00000000..cc2aa12e --- /dev/null +++ b/docs/en/cowboy/2.0/manual/cowboy_req.header/index.html @@ -0,0 +1,258 @@ + + + + + + + + + + + + Nine Nines: cowboy_req:header(3) + + + + + + + + + + + + + + + + +

+ + + +

+ +

cowboy_req:header(3)

+ +

Name

cowboy_req:header - HTTP header

Description

header(Name :: binary(), Req) -> header(Name, Req, undefined)
+header(Name :: binary(), Req, Default) -> binary() | Default
+
+Req :: cowboy_req:req()

Return the value for the given HTTP header.

The header name must be given as a lowercase binary string. +While header names are case insensitive, Cowboy requires them +to be given as lowercase to function properly.

Headers can also be obtained using pattern matching:

#{headers := #{Name := Value}} = Req.

Note that this snippet will crash if the header is missing.

Arguments

+Name +: +
+Desired HTTP header name as a binary string. +
+
+Req +: +
+The Req object. +
+
+Default +: +
+Default value returned when the header is missing. +
+

Return value

The header value is returned as a binary string. When the +header is missing, the default argument is returned.

Changelog

+
+2.0: Only the header value is returned, it is no longer wrapped in a tuple. +
+
+
+1.0: Function introduced. +
+

Examples

Get the accept header

Accept = cowboy_req:header(<<"accept">>, Req).

Get the content-length header with a default value

Length = cowboy_req:header(<<"content-length">>, Req, <<"0">>).

cowboy_req:headers(3)

+ +

Name

cowboy_req:headers - HTTP headers

Description

headers(Req :: cowboy_req:req()) -> cowboy:http_headers()

Return all request headers.

Request headers can also be obtained using pattern matching:

#{headers := Headers} = Req.

Arguments

+Req +: +
+The Req object. +
+

Return value

Headers are returned as a map with keys being lowercase +binary strings, and values as binary strings.

Changelog

+
+2.0: Only the headers are returned, they are no longer wrapped in a tuple. +
+
+
+1.0: Function introduced. +
+

Examples

Get all headers

Headers = cowboy_req:headers(Req).

cowboy_req:host(3)

+ +

Name

cowboy_req:host - URI host name

Description

host(Req :: cowboy_req:req()) -> Host :: binary()

Return the host name of the effective request URI.

The host name can also be obtained using pattern matching:

#{host := Host} = Req.

Arguments

+Req +: +
+The Req object. +
+

Return value

The host name is returned as a lowercase binary string. +It is case insensitive.

Changelog

+
+2.0: Only the host name is returned, it is no longer wrapped in a tuple. +
+
+
+1.0: Function introduced. +
+

Examples

Get the effective request URI’s host name

Host = cowboy_req:host(Req).

cowboy_req:method(3)

+ +

Name

cowboy_req:method - HTTP method

Description

method(Req :: cowboy_req:req()) -> Method :: binary()

Return the request’s HTTP method.

The method can also be obtained using pattern matching:

#{method := Method} = Req.

Arguments

+Req +: +
+The Req object. +
+

Return value

The request’s HTTP method is returned as a binary string. +While methods are case sensitive, standard methods are +always uppercase.

Changelog

+
+2.0: Only the method is returned, it is no longer wrapped in a tuple. +
+
+
+1.0: Function introduced. +
+

Examples

Ensure the request’s method is GET

<<"GET">> = cowboy_req:method(Req).

Allow methods from list

init(Req, State) ->
+    case lists:member(cowboy_req:method(Req), [<<"GET">>, <<"POST">>]) of
+        true -> handle(Req, State);
+        false -> method_not_allowed(Req, State)
+    end.

cowboy_req:path(3)

+ +

Name

cowboy_req:path - URI path

Description

path(Req :: cowboy_req:req()) -> Path :: binary()

Return the path of the effective request URI.

The path can also be obtained using pattern matching:

#{path := Path} = Req.

Arguments

+Req +: +
+The Req object. +
+

Return value

The path is returned as a binary string. It is case sensitive.

Changelog

+
+2.0: Only the path is returned, it is no longer wrapped in a tuple. +
+
+
+1.0: Function introduced. +
+

Examples

Get the effective request URI’s path

Path = cowboy_req:path(Req).

cowboy_req:peer(3)

+ +

Name

cowboy_req:peer - Peer address and port

Description

peer(Req :: cowboy_req:req()) -> Peer
+
+Peer :: {inet:ip_address(), inet:port_number()}

Return the peer’s IP address and port number.

The peer can also be obtained using pattern matching:

#{peer := {IP, Port}} = Req.

Arguments

+Req +: +
+The Req object. +
+

Return value

The peer’s IP address and port number.

The peer is not necessarily the client’s IP address and port. +It is the IP address of the endpoint connecting directly to +the server, which may be a gateway or a proxy.

The forwarded header can be used to get better information +about the different endpoints from the client to the server. +Note however that it is only informative; there is no reliable +way of determining the source of an HTTP request.

Changelog

+
+2.0: Only the peer is returned, it is no longer wrapped in a tuple. +
+
+
+1.0: Function introduced. +
+

Examples

Get the peer IP address and port number.

{IP, Port} = cowboy_req:peer(Req).

cowboy_req:port(3)

+ +

Name

cowboy_req:port - URI port number

Description

port(Req :: cowboy_req:req()) -> Port :: inet:port_number()

Return the port number of the effective request URI.

Note that the port number returned by this function is obtained +by parsing the host header. It may be different from the port +the peer used to connect to Cowboy.

The port number can also be obtained using pattern matching:

#{port := Port} = Req.

Arguments

+Req +: +
+The Req object. +
+

Return value

The port number is returned as an integer.

Changelog

+
+2.0: Only the port number is returned, it is no longer wrapped in a tuple. +
+
+
+1.0: Function introduced. +
+

Examples

Get the effective request URI’s port number

Port = cowboy_req:port(Req).

cowboy_req:qs(3)

+ +

Name

cowboy_req:qs - URI query string

Description

qs(Req :: cowboy_req:req()) -> Qs :: binary()

Return the query string of the effective request URI.

The query string can also be obtained using pattern matching:

#{qs := Qs} = Req.

Arguments

+Req +: +
+The Req object. +
+

Return value

The query string is returned as a binary string. It is case sensitive.

Changelog

+
+2.0: Only the query string is returned, it is no longer wrapped in a tuple. +
+
+
+1.0: Function introduced. +
+

Examples

Get the effective request URI’s query string

Qs = cowboy_req:qs(Req).

cowboy_req:scheme(3)

+ +

Name

cowboy_req:scheme - URI scheme

Description

scheme(Req :: cowboy_req:req()) -> Scheme :: binary()

Return the scheme of the effective request URI.

The scheme can also be obtained using pattern matching:

#{scheme := Scheme} = Req.

Arguments

+Req +: +
+The Req object. +
+

Return value

The scheme is returned as a binary. It is case insensitive.

Cowboy will only set the scheme to <<"http">> or <<"https">>.

Changelog

+
+2.0: Function introduced. +
+

Examples

Redirect HTTP to HTTPS

init(Req0=#{scheme := <<"http">>}, State) ->
+    Req = cowboy_req:reply(302, #{
+        <<"location">> => cowboy_req:uri(Req, #{scheme => <<"https">>})
+    }, Req0),
+    {ok, Req, State};
+init(Req, State) ->
+    {cowboy_rest, Req, State}.

cowboy_req:uri(3)

+ +

Name

cowboy_req:uri - Reconstructed URI

Description

uri(Req :: cowboy_req:req())       -> uri(Req, #{})
+uri(Req :: cowboy_req:req(), Opts) -> URI :: iodata()
+
+Opts :: #{
+    scheme   => iodata()           | undefined,
+    host     => iodata()           | undefined,
+    port     => inet:port_number() | undefined,
+    path     => iodata()           | undefined,
+    qs       => iodata()           | undefined,
+    fragment => iodata()           | undefined
+}

Reconstruct the effective request URI, optionally modifying components.

By default Cowboy will build a URI using the components found +in the request. Options allow disabling or replacing individual +components.

Arguments

+Req +

+The Req object. +

+Opts +

+Map for overriding individual components. +

To replace a component, provide its new value as a binary +string or an iolist. To disable a component, set its value +to undefined.

As this function always returns a valid URI, there are some +things to note:

+
+Disabling the host also disables the scheme and port. +
+
+
+There is no fragment component by default as these are + not sent with the request. +
+
+
+The port number may not appear in the resulting URI if + it is the default port for the given scheme (http: 80; https: 443). +
+

Return value

The reconstructed URI is returned as an iolist or a binary string.

Changelog

+
+2.0: Individual components can be replaced or disabled. +
+
+
+2.0: Only the URI is returned, it is no longer wrapped in a tuple. +
+
+
+2.0: Function introduced. Replaces host_url/1 and url/1. +
+

Examples

With an effective request URI http://example.org/path/to/res?edit=1 +we can have:

Protocol relative form

%% //example.org/path/to/res?edit=1
+cowboy_req:uri(Req, #{scheme => undefined}).

Serialized origin for use in the origin header

%% http://example.org
+cowboy_req:uri(Req, #{path => undefined, qs => undefined}).

HTTP/1.1 origin form (path and query string only)

%% /path/to/res?edit=1
+cowboy_req:uri(Req, #{host => undefined}).

Add a fragment to the URI

%% http://example.org/path/to/res?edit=1#errors
+cowboy_req:uri(Req, #{fragment => <<"errors">>}).

Ensure the scheme is HTTPS

%% https://example.org/path/to/res?edit=1
+cowboy_req:uri(Req, #{scheme => <<"https">>}).

Convert the URI to a binary string

iolist_to_binary(cowboy_req:uri(Req)).

cowboy_req:version(3)

+ +

Name

cowboy_req:version - HTTP version

Description

version(Req :: cowboy_req:req()) -> Version :: cowboy:http_version()

Return the HTTP version used for the request.

The version can also be obtained using pattern matching:

#{version := Version} = Req.

Arguments

+Req +: +
+The Req object. +
+

Return value

The HTTP version used for the request is returned as an +atom. It is provided for informative purposes only.

Changelog

+
+2.0: Only the version is returned, it is no longer wrapped in a tuple. +
+
+
+1.0: Function introduced. +
+

Examples

Get the HTTP version

Version = cowboy_req:version(Req).

Description

The cowboy_req module provides functions to access, manipulate +

The module cowboy_req provides functions to access, manipulate and respond to requests.

The functions in this module follow patterns for their return types, -based on the kind of function.

-
-access: Value -
-
-
-action: ok | {Result, Req} | {Result, Value, Req} -
-
-
-modification: Req -
-
-
-question: boolean() -
-

Whenever Req is returned, you must use this returned value and -ignore any previous you may have had. This value contains various -values which are necessary for Cowboy to keep track of the request -and response states.

All functions which perform an action should only be called once. -This includes reading the request body or replying. Cowboy will -throw an error on the second call when it detects suspicious behavior.

It is highly discouraged to pass the Req object to another process. -Doing so and calling cowboy_req functions from it leads to -undefined behavior.

Types

body_opts() = [Option]

Option = {continue, boolean()}
-        | {length, non_neg_integer()}
-        | {read_length, non_neg_integer()}
-        | {read_timeout, timeout()}
-        | {transfer_decode, transfer_decode_fun(), any()}
-        | {content_decode, content_decode_fun()}

Request body reading options.

cookie_opts() = [Option]

Option = {max_age, non_neg_integer()}
-        | {domain, binary()}
-        | {path, binary()}
-        | {secure, boolean()}
-        | {http_only, boolean()}

Cookie options.

req() - opaque to the user

The Req object.

All functions in this module receive a Req as argument, -and some of them return a new object labelled Req2 in -the function descriptions below.

Request related exports

binding(Name, Req) → binding(Name, Req, undefined)

Alias of cowboy_req:binding/3.

binding(Name, Req, Default) → Value

-Name = atom() -: -
-Binding name. -
-
-Default = any() -: -
-Default value. -
-
-Value = any() | Default -: -
-Binding value. -
-

Return the value for the given binding.

By default the value is a binary, however constraints may change -the type of this value (for example automatically converting -numbers to integer).

bindings(Req) → [{Name, Value}]

-Name = atom() -: -
-Binding name. -
-
-Value = any() -: -
-Binding value. -
-

Return all bindings.

By default the value is a binary, however constraints may change -the type of this value (for example automatically converting -numbers to integer).

header(Name, Req) → header(Name, Req, undefined)

Alias of cowboy_req:header/3.

header(Name, Req, Default) → Value

-Name = binary() -: -
-Request header name. -
-
-Default = any() -: -
-Default value. -
-
-Value = binary() | Default -: -
-Request header value. -
-

Return the value for the given header.

While header names are case insensitive, this function expects -the name to be a lowercase binary.

headers(Req) → Headers

-Headers = cowboy:http_headers() -: -
-Request headers. -
-

Return all headers.

host(Req) → Host

-Host = binary() -: -
-Requested host. -
-

Return the requested host.

host_info(Req) → HostInfo

-HostInfo = cowboy_router:tokens() | undefined -: -
-Extra tokens for the host. -
-

Return the extra tokens from matching against ... during routing.

host_url(Req) → HostURL

-HostURL = binary() | undefined -: -
-Requested URL, without the path component. -
-

Return the requested URL excluding the path component.

This function will always return undefined until the -cowboy_router middleware has been executed.

match_cookies(Fields, Req) → Map

-Fields = cowboy:fields() -: -
-Cookie fields match rules. -
-
-Map = map() -: -
-Cookie fields matched. -
-

Match cookies against the given fields.

Cowboy will only return the cookie values specified in the -fields list, and ignore all others. Fields can be either -the name of the cookie requested; the name along with a -list of constraints; or the name, a list of constraints -and a default value in case the cookie is missing.

This function will crash if the cookie is missing and no -default value is provided. This function will also crash -if a constraint fails.

The name of the cookie must be provided as an atom. The -key of the returned map will be that atom. The value may -be converted through the use of constraints, making this -function able to extract, validate and convert values all -in one step.

match_qs(Fields, Req) → Map

-Fields = cowboy:fields() -: -
-Query string fields match rules. -
-
-Map = map() -: -
-Query string fields matched. -
-

Match the query string against the given fields.

Cowboy will only return the query string values specified -in the fields list, and ignore all others. Fields can be -either the key requested; the key along with a list of -constraints; or the key, a list of constraints and a -default value in case the key is missing.

This function will crash if the key is missing and no -default value is provided. This function will also crash -if a constraint fails.

The key must be provided as an atom. The key of the -returned map will be that atom. The value may be converted -through the use of constraints, making this function able -to extract, validate and convert values all in one step.

meta(Name, Req) → meta(Name, Req, undefined)

Alias for cowboy_req:meta/3.

meta(Name, Req, Default) → Value

-Name = atom() -: -
-Metadata name. -
-
-Default = any() -: -
-Default value. -
-
-Value = any() -: -
-Metadata value. -
-

Return metadata about the request.

method(Req) → Method

-Method = binary() -: -
-Request method. -
-

Return the method.

Methods are case sensitive. Standard methods are always uppercase.

parse_cookies(Req) → [{Name, Value}]

-Name = binary() -: -
-Cookie name. -
-
-Value = binary() -: -
-Cookie value. -
-

Parse and return all cookies.

Cookie names are case sensitive.

parse_header(Name, Req) → see below

Alias of cowboy_req:parse_header/3.

The parse_header/2 function will call parser_header/3 with a -different default value depending on the header being parsed. The -following table summarizes the default values used.

There are four types of functions in this module. They can be +differentiated by their name and their return type:

--+++ - - + + + - - + + + - - + + + - - + + + - - + + +

Header name	Header value	Type	Name pattern	Return type
content-length	`0`	access	no verb, parse_, match_	`Value`
cookie	`[]`	question	has_*	`boolean()`
transfer-encoding	`[<<"identity">>]`	modification	set_*	`Req`
Any other header	`undefined`	action	any other verb	`ok \| {Result, Value, Req}`

Any Req returned must be used in place of the one passed as +argument. Functions that perform an action in particular write +state in the Req object to make sure you are using the function +correctly. For example, it’s only possible to send one response, +and to read the body once.

parse_header(Name, Req, Default) → ParsedValue | Default

-Name = binary() -: -
-Request header name. -
-
-Default = any() -: -
-Default value. -
-
-ParsedValue - see below -: -
-Parsed request header value. -
-

Parse the given header.

While header names are case insensitive, this function expects -the name to be a lowercase binary.

The parsed value differs depending on the header being parsed. The -following table summarizes the different types returned.

- --- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

Header name	Type of parsed header value
accept	`[{{Type, SubType, Params}, Quality, AcceptExt}]`
accept-charset	`[{Charset, Quality}]`
accept-encoding	`[{Encoding, Quality}]`
accept-language	`[{LanguageTag, Quality}]`
authorization	`{AuthType, Credentials}`
content-length	`non_neg_integer()`
content-type	`{Type, SubType, ContentTypeParams}`
cookie	`[{binary(), binary()}]`
expect	`[Expect \| {Expect, ExpectValue, Params}]`
if-match	`'*' \| [{weak \| strong, OpaqueTag}]`
if-modified-since	`calendar:datetime()`
if-none-match	`'*' \| [{weak \| strong, OpaqueTag}]`
if-unmodified-since	`calendar:datetime()`
range	`{Unit, [Range]}`
sec-websocket-protocol	`[binary()]`
transfer-encoding	`[binary()]`
upgrade	`[binary()]`
x-forwarded-for	`[binary()]`

Types for the above table:

Exports

Raw request:

-Type = SubType = Charset = Encoding = LanguageTag = binary() +cowboy_req:method(3) - HTTP method
-AuthType = Expect = OpaqueTag = Unit = binary() +cowboy_req:version(3) - HTTP version
-Params = ContentTypeParams = [{binary(), binary()}] +cowboy_req:scheme(3) - URI scheme
-Quality = 0..1000 +cowboy_req:host(3) - URI host name
-AcceptExt = [{binary(), binary()} | binary()] +cowboy_req:port(3) - URI port number
-Credentials - see below +cowboy_req:path(3) - URI path
-Range = {non_neg_integer(), non_neg_integer() | infinity} | neg_integer() +cowboy_req:qs(3) - URI query string

The cookie names and values, the values of the sec-websocket-protocol -and x-forwarded-for headers, the values in AcceptExt and Params, -the authorization Credentials, the ExpectValue and OpaqueTag -are case sensitive. All values in ContentTypeParams are case sensitive -except the value of the charset parameter, which is case insensitive. -All other values are case insensitive and will be returned as lowercase.

The headers accept, accept-encoding and cookie headers can return -an empty list. Some other headers are expected to have a value if provided -and may crash if the value is missing.

The authorization header parsing code currently only supports basic -HTTP authentication. The Credentials type is thus {Username, Password} -with Username and Password being binary().

The range header value Range can take three forms:

-{From, To}: from From to To units +cowboy_req:uri(3) - Reconstructed URI
-{From, infinity}: everything after From units +cowboy_req:header(3) - HTTP header
--Final: the final Final units +cowboy_req:headers(3) - HTTP headers

An undefined tuple will be returned if Cowboy doesn’t know how -to parse the requested header.

parse_qs(Req) → [{Name, Value}]

-Name = binary() -: -
-Query string field name. -
-
-Value = binary() | true -: -
-Query string field value. -
-

Return the request’s query string as a list of tuples.

The atom true is returned for keys which have no value. -Keys with no value are different from keys with an empty -value in that they do not have a = indicating the presence -of a value.

path(Req) → Path

-Path = binary() -: -
-Requested path. -
-

Return the requested path.

path_info(Req) → PathInfo

-PathInfo = cowboy_router:tokens() | undefined -: +

-Extra tokens for the path. +cowboy_req:peer(3) - Peer address and port
-

Return the extra tokens from matching against ... during routing.

peer(Req) → Peer

-Peer = {inet:ip_address(), inet:port_number()} -: + +

Processed request:

-Peer IP address and port number. +cowboy_req:parse_qs(3) - Parse the query string
- -

Return the client’s IP address and port number.

port(Req) → Port

-Port = inet:port_number() -: + +

-Requested port number. +cowboy_req:match_qs(3) - Match the query string against constraints
-

Return the request’s port.

The port returned by this function is obtained by parsing -the host header. It may be different than the actual port -the client used to connect to the Cowboy server.

qs(Req) → QueryString

-QueryString = binary() -: + +

-Unprocessed query string. +cowboy_req:parse_header(3) - Parse the given HTTP header
-

Return the request’s query string.

set_meta(Name, Value, Req) → Req2

-Name = atom() -: + +

-Metadata name. +cowboy_req:parse_cookies(3) - Parse cookie headers
-
-Value = any() -: + +

-Metadata value. +cowboy_req:match_cookies(3) - Match cookies against constraints
-

Set metadata about the request.

An existing value will be overwritten.

url(Req) → URL

-URL = binary() | undefined -: + +

-Requested URL. +cowboy_req:binding(3) - Access a value bound from the route
-

Return the requested URL.

This function will always return undefined until the -cowboy_router middleware has been executed.

version(Req) → Version

-Version = cowboy:http_version() -: + +

-Client’s advertised HTTP version. +cowboy_req:bindings(3) - Access all values bound from the route
-

Return the HTTP version used for this request.

Request body related exports

body(Req) → body(Req, [])

Alias of cowboy_req:body/2.

body(Req, Opts) → {ok, Data, Req2} | {more, Data, Req2}

-Opts = [body_opt()] -: + +

-Request body reading options. +cowboy_req:host_info(3) - Access the route’s heading host segments
-
-Data = binary() -: + +

-Data read from the body. +cowboy_req:path_info(3) - Access the route’s trailing path segments
-

Read the request body.

This function will read a chunk of the request body. If there is -more data to be read after this function call, then a more tuple -is returned. Otherwise an ok tuple is returned.

Cowboy will automatically send a 100 Continue reply if -required. If this behavior is not desirable, it can be disabled -by setting the continue option to false.

Cowboy will by default attempt to read up to 8MB of the body, -but in chunks of 1MB. It will use a timeout of 15s per chunk. -All these values can be changed using the length, read_length -and read_timeout options respectively. Note that the size -of the data may not be the same as requested as the decoding -functions may grow or shrink it, and Cowboy makes not attempt -at returning an exact amount.

Cowboy will properly handle chunked transfer-encoding by -default. If any other transfer-encoding or content-encoding -has been used for the request, custom decoding functions -can be used. The content_decode and transfer_decode -options allow setting the decode functions manually.

After the body has been streamed fully, Cowboy will remove -the transfer-encoding header from the Req object, and add -the content-length header if it wasn’t already there.

This function can only be called once. Cowboy will not cache -the result of this call.

body_length(Req) → Length

-Length = non_neg_integer() | undefined -: + +

Request body:

-Length of the request body. +cowboy_req:has_body(3) - Is there a request body?
- -

Return the length of the request body.

The length will only be returned if the request does not -use any transfer-encoding and if the content-length header -is present.

body_qs(Req) → body_qs(Req, [{length, 64000}, {read_length, 64000}, {read_timeout, 5000}])

Alias of cowboy_req:body_qs/2.

body_qs(Req, Opts) → {ok, [{Name, Value}], Req2} | {badlength, Req2}

-Opts = [body_opt()] -: + +

-Request body reading options. +cowboy_req:body_length(3) - Body length
-
-Name = binary() -: + +

-Field name. +cowboy_req:read_body(3) - Read the request body
-
-Value = binary() | true -: + +

-Field value. +cowboy_req:read_urlencoded_body(3) - Read and parse a urlencoded request body
-

Return the request body as a list of tuples.

This function will parse the body assuming the content-type -application/x-www-form-urlencoded, commonly used for the -query string.

This function calls body/2 for reading the body, with the -same options it received. By default it will attempt to read -a body of 64KB in one chunk, with a timeout of 5s. If the -body is larger then a badlength tuple is returned.

This function can only be called once. Cowboy will not cache -the result of this call.

has_body(Req) → boolean()

Return whether the request has a body.

part(Req) → part(Req, [{length, 64000}, {read_length, 64000}, {read_timeout, 5000}])

Alias of cowboy_req:part/2.

part(Req, Opts) → {ok, Headers, Req2} | {done, Req2}

-Opts = [body_opt()] -: + +

-Request body reading options. +cowboy_req:read_part(3) - Read the next part of a multipart body
-
-Headers = cow_multipart:headers() -: + +

-Part’s headers. +cowboy_req:read_part_body(3) - Read the current part’s body in a multipart body
-

Read the headers for the next part of the multipart message.

Cowboy will skip any data remaining until the beginning of -the next part. This includes the preamble to the multipart -message but also the body of a previous part if it hasn’t -been read. Both are skipped automatically when calling this -function.

The headers returned are MIME headers, NOT HTTP headers. -They can be parsed using the functions from the cow_multipart -module. In addition, the cow_multipart:form_data/1 function -can be used to quickly figure out multipart/form-data messages. -It takes the list of headers and returns whether this part is -a simple form field or a file being uploaded.

Note that once a part has been read, or skipped, it cannot -be read again.

This function calls body/2 for reading the body, with the -same options it received. By default it will only read chunks -of 64KB with a timeout of 5s. This is tailored for reading -part headers, not for skipping the previous part’s body. -You might want to consider skipping large parts manually.

part_body(Req) → part_body(Req, [])

Alias of cowboy_req:part_body/2.

part_body(Req, Opts) → {ok, Data, Req2} | {more, Data, Req2}

-Opts = [body_opt()] -: + +

Response:

-Request body reading options. +cowboy_req:set_resp_cookie(3) - Set a cookie
- -
-Data = binary() -
-
+
-Part’s body. +cowboy_req:set_resp_header(3) - Set a response header
- -

Read the body of the current part of the multipart message.

This function calls body/2 for reading the body, with the -same options it received. It uses the same defaults.

If there are more data to be read from the socket for this -part, the function will return what it could read inside a -more tuple. Otherwise, it will return an ok tuple.

Calling this function again after receiving a more tuple -will return another chunk of body. The last chunk will be -returned inside an ok tuple.

Note that once the body has been read, fully or partially, -it cannot be read again.

Response related exports

chunk(Data, Req) → ok

-Data = iodata() -: + +

-Chunk data to be sent. +cowboy_req:has_resp_header(3) - Is the given response header set?
-

Send a chunk of data.

This function should be called as many times as needed -to send data chunks after calling chunked_reply/{2,3}.

When the method is HEAD, no data will actually be sent.

If the request uses HTTP/1.0, the data is sent directly -without wrapping it in an HTTP/1.1 chunk, providing -compatibility with older clients.

chunked_reply(StatusCode, Req) → chunked_reply(StatusCode, [], Req)

Alias of cowboy_req:chunked_reply/3.

chunked_reply(StatusCode, Headers, Req) → Req2

-StatusCode = cowboy:http_status() -: + +

-Response status code. +cowboy_req:delete_resp_header(3) - Delete a response header
-
-Headers = cowboy:http_headers() -: + +

-Response headers. +cowboy_req:set_resp_body(3) - Set the response body
-

Send a response using chunked transfer-encoding.

This function effectively sends the response status line -and headers to the client.

This function will not send any body set previously. After -this call the handler must use the chunk/2 function -repeatedly to send the body in as many chunks as needed.

If the request uses HTTP/1.0, the data is sent directly -without wrapping it in an HTTP/1.1 chunk, providing -compatibility with older clients.

This function can only be called once, with the exception -of overriding the response in the onresponse hook.

continue(Req) → ok

Send a 100 Continue intermediate reply.

This reply is required before the client starts sending the -body when the request contains the expect header with the -100-continue value.

Cowboy will send this automatically when required. However -you may want to do it manually by disabling this behavior -with the continue body option and then calling this -function.

delete_resp_header(Name, Req) → Req2

-Name = binary() -: + +

-Response header name. +cowboy_req:has_resp_body(3) - Is there a response body?
-

Delete the given response header.

While header names are case insensitive, this function expects -the name to be a lowercase binary.

has_resp_body(Req) → boolean()

Return whether a response body has been set.

This function will return false if a response body has -been set with a length of 0.

has_resp_header(Name, Req) → boolean()

-Name = binary() -: + +

-Response header name. +cowboy_req:reply(3) - Send the response
-

Return whether the given response header has been set.

While header names are case insensitive, this function expects -the name to be a lowercase binary.

reply(StatusCode, Req) → reply(StatusCode, [], Req)

Alias of cowboy_req:reply/3.

reply(StatusCode, Headers, Req) - see below

Alias of cowboy_req:reply/4, with caveats.

reply(StatusCode, Headers, Body, Req) → Req2

-StatusCode = cowboy:http_status() -: + +

-Response status code. +cowboy_req:stream_reply(3) - Send the response and stream its body
-
-Headers = cowboy:http_headers() -: + +

-Response headers. +cowboy_req:stream_body(3) - Send a chunk of the response body
-
-Body = iodata() -: + +

-Response body. +cowboy_req:push(3) - Push a resource to the client
-

Send a response.

This function effectively sends the response status line, -headers and body to the client, in a single send function -call.

The reply/2 and reply/3 functions will send the body -set previously, if any. The reply/4 function overrides -any body set previously and sends Body instead.

If a body function was set, and reply/2 or reply/3 was -used, it will be called before returning.

No more data can be sent to the client after this function -returns.

This function can only be called once, with the exception -of overriding the response in the onresponse hook.

+ +

set_resp_body(Body, Req) → Req2

-Body = iodata() -: -
-Response body. -
-

Set a response body.

This body will not be sent if chunked_reply/{2,3} or -reply/4 is used, as they override it.

Types

set_resp_body_fun(Fun, Req) → Req2

Alias of cowboy_req:set_resp_body_fun/3.

push_opts()

push_opts() :: #{
+    method => binary(),            %% case sensitive
+    scheme => binary(),            %% lowercase; case insensitive
+    host   => binary(),            %% lowercase; case insensitive
+    port   => inet:port_number(),
+    qs     => binary()             %% case sensitive
+}

Push options.

By default, Cowboy will use the GET method, an empty query string, +and take the scheme, host and port directly from the current +request’s URI.

read_body_opts()

read_body_opts() :: #{
+    length  => non_neg_integer(),
+    period  => non_neg_integer(),
+    timeout => timeout()
+}

Body reading options.

The defaults are function-specific.

set_resp_body_fun(Length, Fun, Req) → Req2

-Fun = fun((Socket, Transport) → ok) -: -
-Fun that will send the response body. -
-
-Socket = inet:socket() -: -
-Socket for this connection. -
-
-Transport = module() -: -
-Transport module for this socket. -
-
-Length = non_neg_integer() -: -
-Length of the response body. -
-

Set a fun for sending the response body.

If a Length is provided, it will be sent in the -content-length header in the response. It is recommended -to set the length if it can be known in advance. Otherwise, -the transfer-encoding header will be set to identity.

This function will only be called if the response is sent -using the reply/2 or reply/3 function.

The fun will receive the Ranch Socket and Transport as -arguments. Only send and sendfile operations are supported.

req()

req() :: #{
+    method  := binary(),               %% case sensitive
+    version := cowboy:http_version() | atom(),
+    scheme  := binary(),               %% lowercase; case insensitive
+    host    := binary(),               %% lowercase; case insensitive
+    port    := inet:port_number(),
+    path    := binary(),               %% case sensitive
+    qs      := binary(),               %% case sensitive
+    headers := cowboy:http_headers(),
+    peer    := {inet:ip_address(), inet:port_number()}
+}

The Req object.

Contains information about the request and response. While +some fields are publicly documented, others aren’t and shouldn’t +be used.

You may add custom fields if required. Make sure to namespace +them by prepending an underscore and the name of your application:

Setting a custom field

Req#{_myapp_auth_method => pubkey}.

set_resp_body_fun(chunked, Fun, Req) → Req2

-Fun = fun((ChunkFun) → ok) -: -
-Fun that will send the response body. -
-
-ChunkFun = funiodata( → ok) -: -
-Fun to call for every chunk to be sent. -
-

Set a fun for sending the response body using chunked transfer-encoding.

This function will only be called if the response is sent -using the reply/2 or reply/3 function.

The fun will receive another fun as argument. This fun is to -be used to send chunks in a similar way to the chunk/2 function, -except the fun only takes one argument, the data to be sent in -the chunk.

resp_body()

resp_body() :: iodata()
+    | {sendfile, Offset, Length, Filename}
+
+Offset   :: non_neg_integer()
+Length   :: pos_integer()
+Filename :: file:name_all()

Response body.

It can take two forms: the actual data to be sent or a +tuple indicating which file to send.

When sending data directly, the type is either a binary or +an iolist. Iolists are an efficient way to build output. +Instead of concatenating strings or binaries, you can simply +build a list containing the fragments you want to send in the +order they should be sent:

Example iolists usage

1> RespBody = ["Hello ", [<<"world">>, $!]].
+["Hello ",[<<"world">>,33]]
+2> io:format("~s~n", [RespBody]).
+Hello world!

When using the sendfile tuple, the Length value is mandatory +and must be higher than 0. It is sent with the response in the +content-length header.

set_resp_cookie(Name, Value, Opts, Req) → Req2

-Name = iodata() -: -
-Cookie name. -
-
-Value = iodata() -: -
-Cookie value. -
-
-Opts = cookie_opts() -: -
-Cookie options. -
-

Set a cookie in the response.

Cookie names are case sensitive.

set_resp_header(Name, Value, Req) → Req2

-Name = binary() -: -
-Response header name. -
-
-Value = iodata() -: -
-Response header value. -
-

Set a response header.

You should use set_resp_cookie/4 instead of this function -to set cookies.

Fetching and listing dependencies only

You can fetch all dependencies recursively without building anything, +with the make fetch-deps command. It follows the same rules described +in the section above.

You can list all dependencies recursively, again without building +anything, with the make list-deps command. It will obviously need +to fetch all dependencies exactly like make fetch-deps. Once +everything is fetched, it prints a sorted list of absolute paths to the +dependencies.

By default, fetch-deps and list-deps work on the BUILD_DEPS +and DEPS lists only. To also fetch/list TEST_DEPS, DOC_DEPS, +REL_DEPS and/or SHELL_DEPS, you have two possibilities:

+
+You can use make fetch-test-deps, make fetch-doc-deps, make + fetch-rel-deps and make fetch-shell-deps commands respectively. + If you want to list them, you can use make list-test-deps, make + list-doc-deps, make list-rel-deps and make list-shell-deps + respectively. +
+
+
+You can use make fetch-deps or make list-deps with the Makefile + variable DEP_TYPES set to a list of dependency types you want. + The types are test, doc, rel and shell respectively. For + example, you can list test and doc dependencies with make list-deps + DEP_TYPES='test doc'. +
+

Note that only first level ‘TEST_DEPS, `DOC_DEPS, REL_DEPS and +SHELL_DEPS are included, not dependencies’ one. In other word, +make list-test-deps lists the TEST_DEPS of your project, but not +TEST_DEPS of the projects yours depend on.

No matter which method you use, BUILD_DEPS and DEPS are always +included.

Internally, the make fetch-* commands store the complete list of +dependencies in files named $(ERLANG_MK_RECURSIVE_DEPS_LIST), +$(ERLANG_MK_RECURSIVE_TEST_DEPS_LIST), +$(ERLANG_MK_RECURSIVE_DOC_DEPS_LIST), +$(ERLANG_MK_RECURSIVE_REL_DEPS_LIST) and +$(ERLANG_MK_RECURSIVE_SHELL_DEPS_LIST). Those files are simply printed +by the make list-* commands.

make list-* commands are made for human beings. If you need the list +of dependencies in a Makefile or a script, you should use the content +of those files directly instead. The reason is that make fetch-* and +make list-* may have unwanted content in their output, such as actual +fetching of dependencies.

Ignoring unwanted dependencies

Sometimes, you may want to ignore dependencies entirely. diff --git a/docs/en/erlang.mk/1/guide/escripts.asciidoc b/docs/en/erlang.mk/1/guide/escripts.asciidoc index 3d68c77b..722dcc6f 100644 --- a/docs/en/erlang.mk/1/guide/escripts.asciidoc +++ b/docs/en/erlang.mk/1/guide/escripts.asciidoc @@ -1,6 +1,83 @@ [[escript]] == Escripts -// @todo Write it. +Escripts are an alternative to release. They are meant to be +used for small command line executables written in Erlang. -Placeholder chapter. +They are not self-contained, unlike xref:relx[releases]. +Erlang must be installed for them to run. This however means +that they are fairly small compared to releases. + +For self-contained executables, check xref:sfx[self-extracting releases]. + +=== Requirements + +Erlang.mk uses `p7zip` by default to generate the escript +archive. Make sure it is installed. On most systems the +package is named `p7zip`; on Ubuntu you need `p7zip-full`. + +If `p7zip` is unavailable, `zip` may be used by setting +the `ESCRIPT_ZIP` variable. For example: + +[source,bash] +$ make escript ESCRIPT_ZIP=zip + +=== Generating an escript + +Run the following command to generate an escript: + +[source,bash] +$ make escript + +This will by default create an escript with the same name as +the project, in the project's directory. If the project is +called `relx` then the escript will be in `./relx`. + +You can run the escript as you would any executable: + +[source,bash] +$ ./relx + +=== Configuration + +You can change the name of the escript by setting `ESCRIPT_NAME`. +The name determines both the default output file name and the +entry module containing the function `main/1`. + +`ESCRIPT_FILE` can be set if you need a different file name +or location. + +The escript header can be entirely customized. The first line +is the shebang, set by `ESCRIPT_SHEBANG`. The second line is +a comment, set by `ESCRIPT_COMMENT`. The third line is the +arguments the VM will use when running the escript, set by +`ESCRIPT_EMU_ARGS`. + +Finally, `ESCRIPT_ZIP` can be set to customize the command used +to create the zip file. Read on for more information. + +=== Extra files + +Generating an escript is a two-part process. First, a zip file +is created with the contents of the escript. Then a header is +added to this file to create the escript. + +It is possible to add commands that will be executed between +the two steps. You can for example add extra files to the zip +archive: + +[source,make] +---- +escript-zip:: + $(verbose) $(ESCRIPT_ZIP) $(ESCRIPT_ZIP_FILE) priv/templates/* +---- + +The `ESCRIPT_ZIP` variable contains the command to run to add +files to the zip archive `ESCRIPT_ZIP_FILE`. + +=== Optimizing for size + +Erlang.mk will by default compile BEAM files with debug +information. You may want to disable this behavior to obtain +smaller escript files. Simply set `ERLC_OPTS` to a value that +does not include `+debug_info`. diff --git a/docs/en/erlang.mk/1/guide/escripts/index.html b/docs/en/erlang.mk/1/guide/escripts/index.html index dec55786..f3ba738f 100644 --- a/docs/en/erlang.mk/1/guide/escripts/index.html +++ b/docs/en/erlang.mk/1/guide/escripts/index.html @@ -69,7 +69,91 @@

Escripts

Placeholder chapter.

Escripts are an alternative to release. They are meant to be +used for small command line executables written in Erlang.

They are not self-contained, unlike releases. +Erlang must be installed for them to run. This however means +that they are fairly small compared to releases.

For self-contained executables, check self-extracting releases.

Requirements

Erlang.mk uses p7zip by default to generate the escript +archive. Make sure it is installed. On most systems the +package is named p7zip; on Ubuntu you need p7zip-full.

If p7zip is unavailable, zip may be used by setting +the ESCRIPT_ZIP variable. For example:

$ make escript ESCRIPT_ZIP=zip

Generating an escript

Run the following command to generate an escript:

$ make escript

This will by default create an escript with the same name as +the project, in the project’s directory. If the project is +called relx then the escript will be in ./relx.

You can run the escript as you would any executable:

$ ./relx

Configuration

You can change the name of the escript by setting ESCRIPT_NAME. +The name determines both the default output file name and the +entry module containing the function main/1.

ESCRIPT_FILE can be set if you need a different file name +or location.

The escript header can be entirely customized. The first line +is the shebang, set by ESCRIPT_SHEBANG. The second line is +a comment, set by ESCRIPT_COMMENT. The third line is the +arguments the VM will use when running the escript, set by +ESCRIPT_EMU_ARGS.

Finally, ESCRIPT_ZIP can be set to customize the command used +to create the zip file. Read on for more information.

Extra files

Generating an escript is a two-part process. First, a zip file +is created with the contents of the escript. Then a header is +added to this file to create the escript.

It is possible to add commands that will be executed between +the two steps. You can for example add extra files to the zip +archive:

The ESCRIPT_ZIP variable contains the command to run to add +files to the zip archive ESCRIPT_ZIP_FILE.

Optimizing for size

Erlang.mk will by default compile BEAM files with debug +information. You may want to disable this behavior to obtain +smaller escript files. Simply set ERLC_OPTS to a value that +does not include +debug_info.

@@ -79,8 +163,8 @@

- - Releases + + Self-extracting releases diff --git a/docs/en/erlang.mk/1/guide/external_plugins_list.asciidoc b/docs/en/erlang.mk/1/guide/external_plugins_list.asciidoc index 317355e6..a194f45d 100644 --- a/docs/en/erlang.mk/1/guide/external_plugins_list.asciidoc +++ b/docs/en/erlang.mk/1/guide/external_plugins_list.asciidoc @@ -28,8 +28,13 @@ as an Erlang.mk plugin. === hexer.mk -An https://github.com/inaka/hexer.mk[Hex plugin] for Erlang.mk. -Hex is a https://hex.pm/[package manager for the Elixir ecosystem]. +An https://github.com/inaka/hexer.mk[Hex plugin] for Erlang.mk +using the `hexer` tool. + +=== hexpm.mk + +Another https://github.com/botsunit/hexpm.mk[Hex plugin] for +Erlang.mk, with support for Hex dependency operators. === jorel diff --git a/docs/en/erlang.mk/1/guide/external_plugins_list/index.html b/docs/en/erlang.mk/1/guide/external_plugins_list/index.html index 803e63b5..9b26460d 100644 --- a/docs/en/erlang.mk/1/guide/external_plugins_list/index.html +++ b/docs/en/erlang.mk/1/guide/external_plugins_list/index.html @@ -104,8 +104,15 @@ as an Erlang.mk plugin.

hexer.mk

An Hex plugin for Erlang.mk. -Hex is a package manager for the Elixir ecosystem.

An Hex plugin for Erlang.mk +using the hexer tool.

hexpm.mk

Another Hex plugin for +Erlang.mk, with support for Hex dependency operators.

diff --git a/docs/en/erlang.mk/1/guide/getting_started.asciidoc b/docs/en/erlang.mk/1/guide/getting_started.asciidoc index 3a7c0d10..ca1391d6 100644 --- a/docs/en/erlang.mk/1/guide/getting_started.asciidoc +++ b/docs/en/erlang.mk/1/guide/getting_started.asciidoc @@ -32,7 +32,7 @@ $ wget https://erlang.mk/erlang.mk Or: [source,bash] -$ curl https://erlang.mk/erlang.mk -o erlang.mk +$ curl -O https://erlang.mk/erlang.mk Alternatively, just https://erlang.mk/erlang.mk[click on this link]. @@ -290,7 +290,7 @@ you can always run `make help`: ---- $ make help erlang.mk (version 1.2.0-642-gccd2b9f) is distributed under the terms of the ISC License. -Copyright (c) 2013-2015 Loïc Hoguin +Copyright (c) 2013-2016 Loïc Hoguin Usage: [V=1] make [target]... diff --git a/docs/en/erlang.mk/1/guide/getting_started/index.html b/docs/en/erlang.mk/1/guide/getting_started/index.html index 0504e949..10bc1ab3 100644 --- a/docs/en/erlang.mk/1/guide/getting_started/index.html +++ b/docs/en/erlang.mk/1/guide/getting_started/index.html @@ -108,7 +108,7 @@ http://www.gnu.org/software/src-highlite --> by Lorenzo Bettini http://www.lorenzobettini.it http://www.gnu.org/software/src-highlite --> -

$ curl https://erlang.mk/erlang.mk -o erlang.mk

$ curl -O https://erlang.mk/erlang.mk

Alternatively, just click on this link.

Make sure you put the file inside the folder we created previously.

@@ -388,7 +388,7 @@ http://www.lorenzobettini.it http://www.gnu.org/software/src-highlite -->

$ make help
 erlang.mk (version 1.2.0-642-gccd2b9f) is distributed under the terms of the ISC License.
-Copyright (c) 2013-2015 Loïc Hoguin <essen@ninenines.eu>
+Copyright (c) 2013-2016 Loïc Hoguin <essen@ninenines.eu>
 
 Usage: [V=1] make [target]...
 
diff --git a/docs/en/erlang.mk/1/guide/index.html b/docs/en/erlang.mk/1/guide/index.html
index 66b34a72..dd2d6927 100644
--- a/docs/en/erlang.mk/1/guide/index.html
+++ b/docs/en/erlang.mk/1/guide/index.html
@@ -122,6 +122,11 @@
 
 
 
+Self-extracting releases
+
+
+
+
 Escripts
 
 
diff --git a/docs/en/erlang.mk/1/guide/installation.asciidoc b/docs/en/erlang.mk/1/guide/installation.asciidoc
index cc18e7f1..f3a52cf4 100644
--- a/docs/en/erlang.mk/1/guide/installation.asciidoc
+++ b/docs/en/erlang.mk/1/guide/installation.asciidoc
@@ -1,24 +1,57 @@
 [[installation]]
 == Installation
 
-This chapter explains how to setup your system in
-order to use Erlang.mk.
-
 === On Unix
 
-Erlang.mk requires GNU Make to be installed. GNU Make 3.81
-or later is required. GNU Make 4.1 or later is recommended,
-as this is the version Erlang.mk is developed on.
+Erlang.mk requires GNU Make to be installed. While it will
+currently work with GNU Make 3.81, support for this version
+is deprecated and will be removed in 2017. We recommend
+GNU Make 4.1 or later.
+
+Git and Erlang/OTP must also be installed.
 
 Some functionality requires that Autoconf 2.59 or later be
 installed, in order to compile Erlang/OTP. Erlang/OTP may
 have further requirements depending on your needs.
 
-Erlang.mk currently requires Erlang/OTP to be installed in
-order to compile Erlang projects.
-
 Some packages may require additional libraries.
 
+==== Linux
+
+The commands to install packages vary between distributions:
+
+.Arch Linux
+[source,bash]
+$ pacman -Sy erlang git make
+
+==== FreeBSD
+
+FreeBSD comes with binary and source packages:
+
+.Install binary packages
+[source,bash]
+$ pkg install erlang git gmake
+
+On FreeBSD the `make` command is BSD Make. Use `gmake` instead.
+
+==== OS X and macOS
+
+While Apple distributes their own GNU Make, their version is
+very old and plagued with numerous bugs. It is recommended
+to install a more recent version from either Homebrew or
+MacPorts:
+
+.Homebrew
+[source,bash]
+$ brew install erlang git homebrew/dupes/make
+
+Homebrew installs GNU Make as `gmake`. The `make` command
+is the one provided by Apple.
+
+.MacPorts
+[source,bash]
+$ sudo port install erlang git gmake
+
 === On Windows
 
 Erlang.mk can be used on Windows inside an MSYS2 environment.
diff --git a/docs/en/erlang.mk/1/guide/installation/index.html b/docs/en/erlang.mk/1/guide/installation/index.html
index 7e4ebfb8..2d711d0f 100644
--- a/docs/en/erlang.mk/1/guide/installation/index.html
+++ b/docs/en/erlang.mk/1/guide/installation/index.html
@@ -69,20 +69,64 @@
 
 Installation
 
-This chapter explains how to setup your system in
-order to use Erlang.mk.
 
 On Unix
 
-Erlang.mk requires GNU Make to be installed. GNU Make 3.81
-or later is required. GNU Make 4.1 or later is recommended,
-as this is the version Erlang.mk is developed on.
+Erlang.mk requires GNU Make to be installed. While it will
+currently work with GNU Make 3.81, support for this version
+is deprecated and will be removed in 2017. We recommend
+GNU Make 4.1 or later.
+Git and Erlang/OTP must also be installed.
 Some functionality requires that Autoconf 2.59 or later be
 installed, in order to compile Erlang/OTP. Erlang/OTP may
 have further requirements depending on your needs.
-Erlang.mk currently requires Erlang/OTP to be installed in
-order to compile Erlang projects.
 Some packages may require additional libraries.
+
+Linux
+The commands to install packages vary between distributions:
+
+Arch Linux
+
+$ pacman -Sy erlang git make
+
+
+FreeBSD
+FreeBSD comes with binary and source packages:
+
+Install binary packages
+
+$ pkg install erlang git gmake
+On FreeBSD the make command is BSD Make. Use gmake instead.
+
+
+OS X and macOS
+While Apple distributes their own GNU Make, their version is
+very old and plagued with numerous bugs. It is recommended
+to install a more recent version from either Homebrew or
+MacPorts:
+
+Homebrew
+
+$ brew install erlang git homebrew/dupes/make
+Homebrew installs GNU Make as gmake. The make command
+is the one provided by Apple.
+
+MacPorts
+
+$ sudo port install erlang git gmake
+
 
 
 
diff --git a/docs/en/erlang.mk/1/guide/releases.asciidoc b/docs/en/erlang.mk/1/guide/releases.asciidoc
index 46183e63..67abe879 100644
--- a/docs/en/erlang.mk/1/guide/releases.asciidoc
+++ b/docs/en/erlang.mk/1/guide/releases.asciidoc
@@ -17,12 +17,11 @@ RELX_CONFIG = $(CURDIR)/webchat.config
 
 Relx does not need to be installed. Erlang.mk will download
 and build it automatically.
-// @todo We are going to fetch relx from repository in the future.
 
 The Relx executable will be saved in the '$(RELX)' file. This
 location defaults to '$(CURDIR)/relx' and can be overriden.
 
-// @todo You can use a custom repository by ???
+// @todo You can use a custom location by ???
 
 === Configuration
 
@@ -56,6 +55,10 @@ the `rel` target can be used:
 [source,bash]
 $ make rel
 
+Erlang.mk always generates a tarball alongside the release,
+which can be directly uploaded to a server. The tarball is
+located at `$(RELX_OUTPUT_DIR)//-.tar.gz`.
+
 === Running the release
 
 Erlang.mk provides a convenience function for running the
@@ -68,3 +71,50 @@ This command will also build the project and generate the
 release if they weren't already. It starts the release in
 _console mode_, meaning you will also have a shell ready to
 use to check things as needed.
+
+=== Upgrading a release
+
+Erlang.mk provides a `relup` target for generating release
+upgrades. Release upgrades allow updating the code and the
+state of a running release without restarting it.
+
+Once your changes are done, you need to update the version
+of the application(s) that will be updated. You also need
+to update the version of the release.
+
+For each application that needs to be updated, an
+http://erlang.org/doc/man/appup.html[appup file]
+must be written. Refer to the Erlang/OTP documentation
+for more details.
+
+For the purpose of this section, assume the initial release
+version was `1`, and the new version is `2`. The name of the
+release will be `example`.
+
+Once all this is done, you can build the tarball for the
+release upgrade:
+
+[source,bash]
+$ make relup
+
+This will create an archive at the root directory of the
+release, `$RELX_OUTPUT_DIR/example/example-2.tar.gz`.
+
+Move the archive to the correct location on the running
+node. From the release's root directory:
+
+[source,bash]
+$ mkdir releases/2/
+$ mv path/to/example-2.tar.gz releases/2/
+
+Finally, upgrade the release:
+
+[source,bash]
+$ bin/example_release upgrade "2/example_release"
+
+Or on Windows:
+
+[source,bash]
+$ bin/example_release.cmd upgrade "2/example_release"
+
+Your release was upgraded!
diff --git a/docs/en/erlang.mk/1/guide/releases/index.html b/docs/en/erlang.mk/1/guide/releases/index.html
index bf102a3c..fc98819e 100644
--- a/docs/en/erlang.mk/1/guide/releases/index.html
+++ b/docs/en/erlang.mk/1/guide/releases/index.html
@@ -123,6 +123,9 @@ by Lorenzo Bettini
 http://www.lorenzobettini.it
 http://www.gnu.org/software/src-highlite -->
 $ make rel

+Erlang.mk always generates a tarball alongside the release, +which can be directly uploaded to a server. The tarball is +located at $(RELX_OUTPUT_DIR)/<name>/<name>-<vsn>.tar.gz. @@ -142,6 +145,58 @@ release if they weren’t already. It starts the release in use to check things as needed. + +Upgrading a release + +Erlang.mk provides a relup target for generating release +upgrades. Release upgrades allow updating the code and the +state of a running release without restarting it. +Once your changes are done, you need to update the version +of the application(s) that will be updated. You also need +to update the version of the release. +For each application that needs to be updated, an +appup file +must be written. Refer to the Erlang/OTP documentation +for more details. +For the purpose of this section, assume the initial release +version was 1, and the new version is 2. The name of the +release will be example. +Once all this is done, you can build the tarball for the +release upgrade: + + +$ make relup +This will create an archive at the root directory of the +release, $RELX_OUTPUT_DIR/example/example-2.tar.gz. +Move the archive to the correct location on the running +node. From the release’s root directory: + + +$ mkdir releases/2/ +$ mv path/to/example-2.tar.gz releases/2/ +Finally, upgrade the release: + + +$ bin/example_release upgrade "2/example_release" +Or on Windows: + + +$ bin/example_release.cmd upgrade "2/example_release" +Your release was upgraded! + + @@ -157,8 +212,8 @@ use to check things as needed. - - Escripts + + Self-extracting releases diff --git a/docs/en/erlang.mk/1/guide/sfx.asciidoc b/docs/en/erlang.mk/1/guide/sfx.asciidoc new file mode 100644 index 00000000..aae2c8d4 --- /dev/null +++ b/docs/en/erlang.mk/1/guide/sfx.asciidoc @@ -0,0 +1,49 @@ +[[sfx]] +== Self-extracting releases + +Erlang.mk allows you to package xref:relx[Relx releases] as +self-extracting archives. These archives contain all the +files in the release and come in the form of a script that +will extract and run the release automatically. + +This allows you to package the release as a single file +that can then be executed. + +This feature is currently experimental. Feedback is much +appreciated. + +=== Generating the self-extracting archive + +To generate a self-extracting release, all you need to do +is pass the `SFX=1` variable to Make when you build the +release: + +[source,bash] +$ make SFX=1 + +This will create a self-extracting archive in +`$RELX_OUTPUT_DIR/.run`. For example if the release +is named `hello_world` and `$RELX_OUTPUT_DIR` is the default, +the file will be located at `_rel/hello_world.run`. + +=== Running the release + +Simply execute the script to get started: + +[source,bash] +---- +$ ./_rel/hello_world.run +Exec: /tmp/tmp.3eeEq7E1ta/erts-8.1/bin/erlexec ... +Root: /tmp/tmp.3eeEq7E1ta +/tmp/tmp.3eeEq7E1ta +Erlang/OTP 19 [erts-8.1] [source] [64-bit] [smp:4:4] ... + +Eshell V8.1 (abort with ^G) +(hello_world@localhost)1> +---- + +As you can see the archive is extracted to a temporary +directory before the release can be started. + +The self-extracting script currently only supports starting +the release in `console` mode. diff --git a/docs/en/erlang.mk/1/guide/sfx/index.html b/docs/en/erlang.mk/1/guide/sfx/index.html new file mode 100644 index 00000000..8433ab9c --- /dev/null +++ b/docs/en/erlang.mk/1/guide/sfx/index.html @@ -0,0 +1,206 @@ + + + + + + + + + + + + Nine Nines: Self-extracting releases + + + + + + + + + + + + + + + + + + + + + 99s + + + + + + + Articles + Talks + Documentation + Consulting & Training + + + + + + + + + + + + + + + + + + + + + + + + + + +Self-extracting releases + +Erlang.mk allows you to package Relx releases as +self-extracting archives. These archives contain all the +files in the release and come in the form of a script that +will extract and run the release automatically. +This allows you to package the release as a single file +that can then be executed. +This feature is currently experimental. Feedback is much +appreciated. + +Generating the self-extracting archive + +To generate a self-extracting release, all you need to do +is pass the SFX=1 variable to Make when you build the +release: + + +$ make SFX=1 +This will create a self-extracting archive in +$RELX_OUTPUT_DIR/<name>.run. For example if the release +is named hello_world and $RELX_OUTPUT_DIR is the default, +the file will be located at _rel/hello_world.run. + + + +Running the release + +Simply execute the script to get started: + + +$ ./_rel/hello_world.run +Exec: /tmp/tmp.3eeEq7E1ta/erts-8.1/bin/erlexec ... +Root: /tmp/tmp.3eeEq7E1ta +/tmp/tmp.3eeEq7E1ta +Erlang/OTP 19 [erts-8.1] [source] [64-bit] [smp:4:4] ... + +Eshell V8.1 (abort with ^G) +(hello_world@localhost)1> +As you can see the archive is extracted to a temporary +directory before the release can be started. +The self-extracting script currently only supports starting +the release in console mode. + + + + + + + + + + + + + Releases + + + + + + Escripts + + + + + + + + + + + + + + Erlang.mk + 1 + + User Guide + + + + + + + + +Navigation + +Version select + + + + + 1 + + + + + + + + + + + + + ↑ Scroll to top + + + Contact us Contribute to this site + + + + + + Copyright © Loïc Hoguin 2012-2016 + + + + + + + + + + + + + + diff --git a/docs/en/ranch/1.2/manual/ranch_ssl/index.html b/docs/en/ranch/1.2/manual/ranch_ssl/index.html index 4d358da7..b486f5ed 100644 --- a/docs/en/ranch/1.2/manual/ranch_ssl/index.html +++ b/docs/en/ranch/1.2/manual/ranch_ssl/index.html @@ -92,6 +92,7 @@ by Lorenzo Bettini http://www.lorenzobettini.it http://www.gnu.org/software/src-highlite --> ssl_opt() = {alpn_preferred_protocols, [binary()]} + | {beast_mitigation, one_n_minus_one | zero_n | disabled} | {cacertfile, string()} | {cacerts, [public_key:der_encoded()]} | {cert, public_key:der_encoded()} @@ -110,6 +111,7 @@ http://www.gnu.org/software/src-highlite --> | {keyfile, string()} | {log_alert, boolean()} | {next_protocols_advertised, [binary()]} + | {padding_check, boolean()} | {partial_chain, fun(([public_key:der_encoded()]) -> {trusted_ca, public_key:der_encoded()} | unknown_ca)} | {password, string()} | {psk_identity, string()} @@ -120,6 +122,7 @@ http://www.gnu.org/software/src-highlite --> | {sni_fun, fun()} | {sni_hosts, [{string(), ssl_opt()}]} | {user_lookup_fun, {fun(), any()}} + | {v2_hello_compatible, boolean()} | {verify, ssl:verify_type()} | {verify_fun, {fun(), any()}} | {versions, [atom()]}. @@ -151,6 +154,14 @@ alpn_preferred_protocols +beast_mitigation + + + + Change the BEAST mitigation strategy for SSL-3.0 and TLS-1.0 to interoperate with legacy software. + + + cacertfile @@ -303,6 +314,14 @@ nodelay (true) +padding_check + + + + Allow disabling the block cipher padding check for TLS-1.0 to be able to interoperate with legacy software. + + + partial_chain @@ -383,6 +402,14 @@ user_lookup_fun +v2_hello_compatible + + + + Accept clients that send hello messages in SSL-2.0 format while offering supported SSL/TLS versions. + + + verify (verify_none) diff --git a/docs/index.xml b/docs/index.xml index c28a3425..b4a331ed 100644 --- a/docs/index.xml +++ b/docs/index.xml @@ -52,6 +52,61 @@ </li> <li> +<a href="cowboy_req.header">cowboy_req:header(3)</a> + +</li> +<li> + +<a href="cowboy_req.headers">cowboy_req:headers(3)</a> + +</li> +<li> + +<a href="cowboy_req.host">cowboy_req:host(3)</a> + +</li> +<li> + +<a href="cowboy_req.method">cowboy_req:method(3)</a> + +</li> +<li> + +<a href="cowboy_req.path">cowboy_req:path(3)</a> + +</li> +<li> + +<a href="cowboy_req.peer">cowboy_req:peer(3)</a> + +</li> +<li> + +<a href="cowboy_req.port">cowboy_req:port(3)</a> + +</li> +<li> + +<a href="cowboy_req.qs">cowboy_req:qs(3)</a> + +</li> +<li> + +<a href="cowboy_req.scheme">cowboy_req:scheme(3)</a> + +</li> +<li> + +<a href="cowboy_req.uri">cowboy_req:uri(3)</a> + +</li> +<li> + +<a href="cowboy_req.version">cowboy_req:version(3)</a> + +</li> +<li> + <a href="cowboy_rest">cowboy_rest(3)</a> </li> @@ -374,6 +429,11 @@ </li> <li> +<a href="sfx/">Self-extracting releases</a> + +</li> +<li> + <a href="escripts/">Escripts</a> </li> @@ -1126,10 +1186,10 @@ http://www.gnu.org/software/src-highlite --> | {Name, Constraints} | {Name, Constraints, Default}] -Name :: atom() +Name :: atom() Constraints :: Constraint | [Constraint] -Constraint :: cowboy_constraints:constraint() -Default :: any()</tt></pre></div></div> +Constraint :: cowboy_constraints:constraint() +Default :: any()</tt></pre></div></div> <div class="paragraph">Fields description for match operations.</div> <div class="paragraph">This type is used in <a href="../cowboy_router">cowboy_router(3)</a> for matching bindings and in the match functions found in @@ -1439,9 +1499,9 @@ Value The new value. +<div class="paragraph">The type of the value differs depending on the key.</div> </dd> </dl></div> -<div class="paragraph">The type of the value differs depending on the key.</div> </div> </div> <div class="sect1"> diff --git a/donate/index.html b/donate/index.html index 080cf380..c66d8fdc 100644 --- a/donate/index.html +++ b/donate/index.html @@ -333,6 +333,30 @@ work on open source software including Cowboy and Erlang.mk. + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/index.html b/index.html index c16e0898..5a02a585 100644 --- a/index.html +++ b/index.html @@ -473,6 +473,30 @@ + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/services/index.html b/services/index.html index 1228b964..4d596ed9 100644 --- a/services/index.html +++ b/services/index.html @@ -418,6 +418,30 @@ work on open source software including Cowboy and Erlang.mk. + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/sitemap.xml b/sitemap.xml index ca0d8506..62618969 100644 --- a/sitemap.xml +++ b/sitemap.xml @@ -206,6 +206,50 @@ https://ninenines.eu/docs/en/cowboy/2.0/manual/cowboy_req/ + + https://ninenines.eu/docs/en/cowboy/2.0/manual/cowboy_req.header/ + + + + https://ninenines.eu/docs/en/cowboy/2.0/manual/cowboy_req.headers/ + + + + https://ninenines.eu/docs/en/cowboy/2.0/manual/cowboy_req.host/ + + + + https://ninenines.eu/docs/en/cowboy/2.0/manual/cowboy_req.method/ + + + + https://ninenines.eu/docs/en/cowboy/2.0/manual/cowboy_req.path/ + + + + https://ninenines.eu/docs/en/cowboy/2.0/manual/cowboy_req.peer/ + + + + https://ninenines.eu/docs/en/cowboy/2.0/manual/cowboy_req.port/ + + + + https://ninenines.eu/docs/en/cowboy/2.0/manual/cowboy_req.qs/ + + + + https://ninenines.eu/docs/en/cowboy/2.0/manual/cowboy_req.scheme/ + + + + https://ninenines.eu/docs/en/cowboy/2.0/manual/cowboy_req.uri/ + + + + https://ninenines.eu/docs/en/cowboy/2.0/manual/cowboy_req.version/ + + https://ninenines.eu/docs/en/cowboy/2.0/manual/cowboy_rest/ @@ -383,11 +427,11 @@ - https://ninenines.eu/docs/en/erlang.mk/1/guide/escripts/ + https://ninenines.eu/docs/en/erlang.mk/1/guide/sfx/ - https://ninenines.eu/docs/en/erlang.mk/1/guide/compat/ + https://ninenines.eu/docs/en/erlang.mk/1/guide/escripts/ @@ -395,7 +439,7 @@ - https://ninenines.eu/docs/en/erlang.mk/1/guide/asciidoc/ + https://ninenines.eu/docs/en/erlang.mk/1/guide/compat/ @@ -403,7 +447,7 @@ - https://ninenines.eu/docs/en/erlang.mk/1/guide/edoc/ + https://ninenines.eu/docs/en/erlang.mk/1/guide/asciidoc/ @@ -411,17 +455,21 @@ - https://ninenines.eu/docs/en/erlang.mk/1/guide/shell/ + https://ninenines.eu/docs/en/erlang.mk/1/guide/edoc/ - https://ninenines.eu/docs/en/erlang.mk/1/guide/eunit/ + https://ninenines.eu/docs/en/erlang.mk/1/guide/shell/ https://ninenines.eu/docs/en/cowboy/2.0/guide/req/ + + https://ninenines.eu/docs/en/erlang.mk/1/guide/eunit/ + + https://ninenines.eu/docs/en/cowboy/2.0/guide/req_body/ @@ -435,19 +483,19 @@ - https://ninenines.eu/docs/en/erlang.mk/1/guide/coverage/ + https://ninenines.eu/docs/en/cowboy/2.0/guide/cookies/ - https://ninenines.eu/docs/en/cowboy/2.0/guide/cookies/ + https://ninenines.eu/docs/en/erlang.mk/1/guide/coverage/ - https://ninenines.eu/docs/en/erlang.mk/1/guide/ci/ + https://ninenines.eu/docs/en/cowboy/2.0/guide/multipart/ - https://ninenines.eu/docs/en/cowboy/2.0/guide/multipart/ + https://ninenines.eu/docs/en/erlang.mk/1/guide/ci/ @@ -463,19 +511,19 @@ - https://ninenines.eu/docs/en/erlang.mk/1/guide/external_plugins/ + https://ninenines.eu/docs/en/cowboy/2.0/guide/rest_handlers/ - https://ninenines.eu/docs/en/cowboy/2.0/guide/rest_handlers/ + https://ninenines.eu/docs/en/erlang.mk/1/guide/external_plugins/ - https://ninenines.eu/docs/en/erlang.mk/1/guide/external_plugins_list/ + https://ninenines.eu/docs/en/cowboy/2.0/guide/rest_flowcharts/ - https://ninenines.eu/docs/en/cowboy/2.0/guide/rest_flowcharts/ + https://ninenines.eu/docs/en/erlang.mk/1/guide/external_plugins_list/ @@ -487,11 +535,11 @@ - https://ninenines.eu/docs/en/erlang.mk/1/guide/history/ + https://ninenines.eu/docs/en/cowboy/2.0/guide/ws_protocol/ - https://ninenines.eu/docs/en/cowboy/2.0/guide/ws_protocol/ + https://ninenines.eu/docs/en/erlang.mk/1/guide/history/ -- cgit v1.2.3

cowboy_req:header(3)

Name

Description

Arguments

Return value

Changelog

Examples

See also

+ Cowboy + 2.0 + Function Reference + +

Navigation

Version select

cowboy_req:headers(3)

Name

Description

Arguments

Return value

Changelog

Examples

See also

+ Cowboy + 2.0 + Function Reference + +

Navigation

Version select

cowboy_req:host(3)

Name

Description

Arguments

Return value

Changelog

Examples

See also

+ Cowboy + 2.0 + Function Reference + +

Navigation

Version select

cowboy_req:method(3)

Name

Description

Arguments

Return value

Changelog

Examples

See also

+ Cowboy + 2.0 + Function Reference + +

Navigation

Version select

cowboy_req:path(3)

Name

Description

Arguments

Return value

Changelog

Examples

See also

+ Cowboy + 2.0 + Function Reference + +

Navigation

Version select

cowboy_req:peer(3)

Name

Description

Arguments

Return value

Changelog

Examples

See also

+ Cowboy + 2.0 + Function Reference + +

Navigation

Version select

cowboy_req:port(3)

Name

Description

Arguments

Return value

Changelog

Examples

See also

+ Cowboy + 2.0 + Function Reference + +

Navigation

Version select

cowboy_req:qs(3)

Name

Description