Skip to content

Commit

Permalink
Deploying to gh-pages from @ 403b2e0 🚀
Browse files Browse the repository at this point in the history
  • Loading branch information
@balat
balat committed Aug 23, 2024
1 parent 9b79b9e commit 082e0e4
Show file tree
Hide file tree
Showing 2 changed files with 144 additions and 30 deletions.
87 changes: 72 additions & 15 deletions dev/manual/basics-server.html
View file
Original file line number Diff line number Diff line change
Expand Up @@ -84,7 +84,44 @@
to function <span class="teletype">f</span>&quot;.
</p><p>Syntax <span class="teletype">let%lwt x = p in e</span> is equivalent to <span class="teletype">Lwt.bind p (fun x -&gt; e)</span>
and makes it very natural to sequentialize computations without blocking the rest
of the program.</p></div><p>To learn Lwt, read this <a href="lwt" class="ocsimore_phrasing_link">short tutorial</a>, or its <a href=".././../../lwt/" class="ocsimore_phrasing_link">user manual</a>.</p></section><section class="docblock"><header><h2>Eliom: Services</h2></header><p>The following code shows how to create a service that answers
of the program.</p></div><p>To learn Lwt, read this <a href="lwt" class="ocsimore_phrasing_link">short tutorial</a>, or its <a href=".././../../lwt/" class="ocsimore_phrasing_link">user manual</a>.</p></section><section class="docblock"><header><h2>Ocsigen Server: A full featured extensible Web server in OCaml</h2></header><p>Ocsigen Server can be used either as a library for you OCaml programs, or as
an executable, taking its configuration from a file (and with dynamic linking).
</p><p>Extensions add features to the server. For example, Staticmod makes it possible
to serve static files, Deflatemod to compress the output, Redirectmod to
configure redirections etc.
</p><p>Install Ocsigen Server with:
</p><pre>opam install ocsigenserver
</pre><h3>Use as a library</h3><p>To include a Web server in your OCaml program, just add
package <span class="teletype">ocsigenserver</span> to your Dune file, together with all the extensions
you need. For example:
</p><pre>(executable
(public_name mysite)
(name main)
(libraries
ocsigenserver
ocsigenserver.ext.staticmod))
</pre><p>Do
<span class="teletype">dune init project mysite</span>
Then copy the dune file in directory <span class="teletype">bin/</span>.
</p><p>The following command will launch a server, serving static files from
directory <span class="teletype">static</span>:
</p><pre class=""><code class="language-ocaml translatable">let () =
Ocsigen_server.start [ Ocsigen_server.host [Staticmod.run ~dir:&quot;static&quot; ()]]</code></pre><p>Put this in file <span class="teletype">main.ml</span>, and run <span class="teletype">dune exec mysite</span>.
</p><p>By default, the server runs on port 8080.
</p><h3>Use as an executable</h3><p>Alternatively, you can run command <span class="teletype">ocsigenserver</span> with a configuration
file:
</p><pre>ocsigenserver -c mysite.conf
</pre><p>The following configuration file corresponds to the program above:
</p><pre>&lt;ocsigen&gt;
&lt;server&gt;
&lt;port&gt;8080&lt;/port&gt;
&lt;extension findlib-package=&quot;ocsigenserver.ext.staticmod&quot;/&gt;
&lt;host&gt;
&lt;static dir=&quot;static&quot; /&gt;
&lt;/host&gt;
&lt;/server&gt;
&lt;/ocsigen&gt;
</pre></section><section class="docblock"><header><h2>Eliom: Services</h2></header><p>The following code shows how to create a service that answers
for requests at URL <span class="teletype">http://.../aaa/bbb</span>, by invoking an
Ocaml function <span class="teletype">f</span> of type:
</p><pre class=""><code class="language-ocaml translatable">f : (string * string) list -&gt; unit -&gt; string Lwt.t</code></pre><p>Function <span class="teletype">f</span> generates HTML as a string, taking as first argument the list
Expand All @@ -105,17 +142,44 @@
f</code></pre><p><span class="teletype">Eliom_service.Get Eliom_parameter.any</span> means that the service uses the GET HTTP method
and takes any GET parameter. The first parameter of function <span class="teletype">f</span> is an association list of GET parameters.
</p><p>Module <span class="teletype">Eliom_registration.Html_text</span> is used to register a service sending
HTML as strings. But we recommend to used typed-HTML instead (see below).</p></section><section class="docblock"><header><h2>Compiling</h2></header><p>Eliom provides an helper program called <span class="teletype">eliom-distillery</span> to create your projects easily, with the right dune configuration and all default directories you usually need for a Web application (static files, server logs, database, etc.). We will show how to use eliom-distillery in another section below.
</p><p>In this section, we will show how to compile and run a <em>server-side only</em> Web site by creating your project manually.
HTML as strings. But we recommend to used typed-HTML instead (see below).</p></section><section class="docblock"><header><h2>Compiling</h2></header><p>In this section, we will show how to compile and run a <em>server-side only</em> Web site by creating your project manually.
</p><p>First, create the directories will we use for data (logs, etc.):
</p><pre>mkdir -p local/var/log/mysite
mkdir -p local/var/data/mysite
mkdir -p local/var/run
</pre><h3>Build an executable</h3><p>This section shows how to create a static executable for you program
(without configuration file).
</p><p>Run the following command:
</p><pre>opam install ocsipersist-sqlite eliom
</pre><p>Add packages <span class="teletype">ocsipersist.sqlite</span> and <span class="teletype">eliom.server</span> to file
<span class="teletype">bin/dune</span>, in the &quot;libraries&quot; section.
</p><p>Copy the definition and registration of service <span class="teletype">myservice</span> at the beginning
of file <span class="teletype">bin/main.ml</span>,
and replace the call to <span class="teletype">Ocsigen_server.start</span> by the following lines:
</p><pre class=""><code class="language-ocaml translatable">let () =
Ocsigen_server.start
~command_pipe:&quot;local/var/run/mysite-cmd&quot;
~logdir:&quot;local/var/log/mysite&quot;
~datadir:&quot;local/var/data/mysite&quot;
[
Ocsigen_server.host
[ Staticmod.run ~dir:&quot;local/var/www/mysite&quot; ()
; Eliom.run () ]
]</code></pre><p>Build and execute the program with:
</p><pre>dune exec mysite
</pre><p>Open URL <span class="teletype">http://localhost:8080/aaa/bbb</span> with your browser.
</p><h3>Use with ocsigenserver</h3><p>Alternatively, you can decide to build your Eliom app as a library and
load it dynamically into ocsigenserver using a configuration file.
</p><pre>opam install ocsipersist-sqlite eliom
dune init proj --kind=lib mysite
cd mysite
</pre><p>Add <span class="teletype">(libraries eliom.server)</span> into file <span class="teletype">lib/dune</span>, in the library section.
</pre><p>Add <span class="teletype">(libraries eliom.server)</span> into file <span class="teletype">lib/dune</span>.
</p><p>Create your <span class="teletype">.ml</span> files in directory <span class="teletype">lib</span>.
For example, copy the definition and registration of service <span class="teletype">myservice</span> above.
</p><p>Compile:
</p><pre>dune build
</pre><p>Create a configuration file <span class="teletype">mysite.conf</span> with this content on your project root directory:
</pre><p>Create a configuration file <span class="teletype">mysite.conf</span>
with this content on your project root directory:
</p><pre>&lt;ocsigen&gt;
&lt;server&gt;
&lt;port&gt;8080&lt;/port&gt;
Expand All @@ -126,22 +190,15 @@

&lt;commandpipe&gt;local/var/run/mysite-cmd&lt;/commandpipe&gt;
&lt;extension findlib-package=&quot;ocsigenserver.ext.staticmod&quot;/&gt;
&lt;extension findlib-package=&quot;ocsipersist.sqlite&quot;/&gt;
&lt;extension findlib-package=&quot;eliom.server&quot;&gt;
&lt;ignoredgetparams regexp=&quot;utm_[a-z]*|[a-z]*clid|li_fat_id&quot;/&gt;
&lt;/extension&gt;
&lt;extension findlib-package=&quot;ocsipersist-sqlite&quot;/&gt;
&lt;extension findlib-package=&quot;eliom.server&quot;/&gt;
&lt;host hostfilter=&quot;*&quot;&gt;
&lt;static dir=&quot;static&quot; /&gt;
&lt;static dir=&quot;local/var/www/mysite/eliom&quot; /&gt;
&lt;static dir=&quot;local/var/www/mysite&quot; /&gt;
&lt;eliommodule module=&quot;_build/default/lib/mysite.cma&quot; /&gt;
&lt;eliom/&gt;
&lt;/host&gt;
&lt;/server&gt;
&lt;/ocsigen&gt;
</pre><p>Create the missing directories:
</p><pre>mkdir -p local/var/log/mysite
mkdir -p local/var/data/mysite
mkdir -p local/var/run
</pre><p>Launch the application:
</p><pre>ocsigenserver -c mysite.conf
</pre><p>Open URL <span class="teletype">http://localhost:8080/aaa/bbb</span> with your browser.</p></section><section class="docblock"><header><h2>TyXML: typing HTML</h2></header><p>TyXML statically checks that your OCaml functions will never
Expand Down
87 changes: 72 additions & 15 deletions dev/manual/basics.html
View file
Original file line number Diff line number Diff line change
Expand Up @@ -78,7 +78,44 @@
to function <span class="teletype">f</span>&quot;.
</p><p>Syntax <span class="teletype">let%lwt x = p in e</span> is equivalent to <span class="teletype">Lwt.bind p (fun x -&gt; e)</span>
and makes it very natural to sequentialize computations without blocking the rest
of the program.</p></div><p>To learn Lwt, read this <a href="lwt" class="ocsimore_phrasing_link">short tutorial</a>, or its <a href=".././../../lwt/" class="ocsimore_phrasing_link">user manual</a>.</p></section><section class="docblock"><header><h2>TyXML: typing HTML</h2></header><p>TyXML statically checks that your OCaml functions will never
of the program.</p></div><p>To learn Lwt, read this <a href="lwt" class="ocsimore_phrasing_link">short tutorial</a>, or its <a href=".././../../lwt/" class="ocsimore_phrasing_link">user manual</a>.</p></section><section class="docblock"><header><h2>Ocsigen Server: A full featured extensible Web server in OCaml</h2></header><p>Ocsigen Server can be used either as a library for you OCaml programs, or as
an executable, taking its configuration from a file (and with dynamic linking).
</p><p>Extensions add features to the server. For example, Staticmod makes it possible
to serve static files, Deflatemod to compress the output, Redirectmod to
configure redirections etc.
</p><p>Install Ocsigen Server with:
</p><pre>opam install ocsigenserver
</pre><h3>Use as a library</h3><p>To include a Web server in your OCaml program, just add
package <span class="teletype">ocsigenserver</span> to your Dune file, together with all the extensions
you need. For example:
</p><pre>(executable
(public_name mysite)
(name main)
(libraries
ocsigenserver
ocsigenserver.ext.staticmod))
</pre><p>Do
<span class="teletype">dune init project mysite</span>
Then copy the dune file in directory <span class="teletype">bin/</span>.
</p><p>The following command will launch a server, serving static files from
directory <span class="teletype">static</span>:
</p><pre class=""><code class="language-ocaml translatable">let () =
Ocsigen_server.start [ Ocsigen_server.host [Staticmod.run ~dir:&quot;static&quot; ()]]</code></pre><p>Put this in file <span class="teletype">main.ml</span>, and run <span class="teletype">dune exec mysite</span>.
</p><p>By default, the server runs on port 8080.
</p><h3>Use as an executable</h3><p>Alternatively, you can run command <span class="teletype">ocsigenserver</span> with a configuration
file:
</p><pre>ocsigenserver -c mysite.conf
</pre><p>The following configuration file corresponds to the program above:
</p><pre>&lt;ocsigen&gt;
&lt;server&gt;
&lt;port&gt;8080&lt;/port&gt;
&lt;extension findlib-package=&quot;ocsigenserver.ext.staticmod&quot;/&gt;
&lt;host&gt;
&lt;static dir=&quot;static&quot; /&gt;
&lt;/host&gt;
&lt;/server&gt;
&lt;/ocsigen&gt;
</pre></section><section class="docblock"><header><h2>TyXML: typing HTML</h2></header><p>TyXML statically checks that your OCaml functions will never
generate wrong HTML. For example a program that could generate a paragraph
containing another paragraph will be rejected at compile time.
</p><p>Example of use:
Expand Down Expand Up @@ -187,17 +224,44 @@
~src:(Eliom_content.Html.F.make_uri
(Eliom_service.static_dir ())
[&quot;dir&quot; ; &quot;image.jpg&quot;])
()</code></pre></section><section class="docblock"><header><h2>Compiling</h2></header><p>Eliom provides an helper program called <span class="teletype">eliom-distillery</span> to create your projects easily, with the right dune configuration and all default directories you usually need for a Web application (static files, server logs, database, etc.). We will show how to use eliom-distillery in another section below.
</p><p>In this section, we will show how to compile and run a <em>server-side only</em> Web site by creating your project manually.
()</code></pre></section><section class="docblock"><header><h2>Compiling</h2></header><p>In this section, we will show how to compile and run a <em>server-side only</em> Web site by creating your project manually.
</p><p>First, create the directories will we use for data (logs, etc.):
</p><pre>mkdir -p local/var/log/mysite
mkdir -p local/var/data/mysite
mkdir -p local/var/run
</pre><h3>Build an executable</h3><p>This section shows how to create a static executable for you program
(without configuration file).
</p><p>Run the following command:
</p><pre>opam install ocsipersist-sqlite eliom
</pre><p>Add packages <span class="teletype">ocsipersist.sqlite</span> and <span class="teletype">eliom.server</span> to file
<span class="teletype">bin/dune</span>, in the &quot;libraries&quot; section.
</p><p>Copy the definition and registration of service <span class="teletype">myservice</span> at the beginning
of file <span class="teletype">bin/main.ml</span>,
and replace the call to <span class="teletype">Ocsigen_server.start</span> by the following lines:
</p><pre class=""><code class="language-ocaml translatable">let () =
Ocsigen_server.start
~command_pipe:&quot;local/var/run/mysite-cmd&quot;
~logdir:&quot;local/var/log/mysite&quot;
~datadir:&quot;local/var/data/mysite&quot;
[
Ocsigen_server.host
[ Staticmod.run ~dir:&quot;local/var/www/mysite&quot; ()
; Eliom.run () ]
]</code></pre><p>Build and execute the program with:
</p><pre>dune exec mysite
</pre><p>Open URL <span class="teletype">http://localhost:8080/foo?myparam=Hello&amp;i=27</span> with your browser.
</p><h3>Use with ocsigenserver</h3><p>Alternatively, you can decide to build your Eliom app as a library and
load it dynamically into ocsigenserver using a configuration file.
</p><pre>opam install ocsipersist-sqlite eliom
dune init proj --kind=lib mysite
cd mysite
</pre><p>Add <span class="teletype">(libraries eliom.server)</span> into file <span class="teletype">lib/dune</span>, in the library section.
</pre><p>Add <span class="teletype">(libraries eliom.server)</span> into file <span class="teletype">lib/dune</span>.
</p><p>Create your <span class="teletype">.ml</span> files in directory <span class="teletype">lib</span>.
For example, copy the definition and registration of service <span class="teletype">myservice</span> above.
</p><p>Compile:
</p><pre>dune build
</pre><p>Create a configuration file <span class="teletype">mysite.conf</span> with this content on your project root directory:
</pre><p>Create a configuration file <span class="teletype">mysite.conf</span>
with this content on your project root directory:
</p><pre>&lt;ocsigen&gt;
&lt;server&gt;
&lt;port&gt;8080&lt;/port&gt;
Expand All @@ -208,22 +272,15 @@

&lt;commandpipe&gt;local/var/run/mysite-cmd&lt;/commandpipe&gt;
&lt;extension findlib-package=&quot;ocsigenserver.ext.staticmod&quot;/&gt;
&lt;extension findlib-package=&quot;ocsipersist.sqlite&quot;/&gt;
&lt;extension findlib-package=&quot;eliom.server&quot;&gt;
&lt;ignoredgetparams regexp=&quot;utm_[a-z]*|[a-z]*clid|li_fat_id&quot;/&gt;
&lt;/extension&gt;
&lt;extension findlib-package=&quot;ocsipersist-sqlite&quot;/&gt;
&lt;extension findlib-package=&quot;eliom.server&quot;/&gt;
&lt;host hostfilter=&quot;*&quot;&gt;
&lt;static dir=&quot;static&quot; /&gt;
&lt;static dir=&quot;local/var/www/mysite/eliom&quot; /&gt;
&lt;static dir=&quot;local/var/www/mysite&quot; /&gt;
&lt;eliommodule module=&quot;_build/default/lib/mysite.cma&quot; /&gt;
&lt;eliom/&gt;
&lt;/host&gt;
&lt;/server&gt;
&lt;/ocsigen&gt;
</pre><p>Create the missing directories:
</p><pre>mkdir -p local/var/log/mysite
mkdir -p local/var/data/mysite
mkdir -p local/var/run
</pre><p>Launch the application:
</p><pre>ocsigenserver -c mysite.conf
</pre><p>Open URL <span class="teletype">http://localhost:8080/foo?myparam=Hello&amp;i=27</span> with your browser.</p></section><section class="docblock"><header><h2>Forms and links</h2></header><p>Functions <span><a href=".././../../eliom/latest/api/server/Eliom_form_sigs.LINKS#VALa">Eliom_content.Html.F.a</a></span> and
Expand Down

0 comments on commit 082e0e4

Please sign in to comment.