Skip to content

Commit 321fdd2

Browse files
SimonJFSimonJF
committed
Finish installation, add getting started
1 parent 07b48e2 commit 321fdd2

File tree

2 files changed

+176
-1
lines changed

2 files changed

+176
-1
lines changed

‎getting-started.rst

Lines changed: 164 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,167 @@
1+
.. _getting_started:
2+
13
Getting started
24
===============
35

4-
TODO: Getting started guide
6+
In this section, we will see how to get up and running with the Links REPL, as
7+
well as running the web examples.
8+
9+
Running the REPL
10+
----------------
11+
12+
The Links REPL (Read-Eval-Print-Loop) allows you to run commands and evaluate
13+
expressions interactively. Typing ``linx`` on a terminal should bring up an
14+
interactive window::
15+
16+
_ _ __ _ _ __ ___
17+
/ | | | \ | | |/ / / ._\
18+
| | | | , \| | / \ \
19+
| |___| | |\ \ | |\ \ _\ \
20+
|_____|_|_| \__|_| \_|____/
21+
Welcome to Links version 0.9 (Burghmuirhead)
22+
links>
23+
24+
You can now write an expression, and Links will show you the result. Note that
25+
in interactive mode, each expression must be terminated with a semicolon.
26+
27+
.. code-block::
28+
29+
links> 1 + 2 + 3;;
30+
6 : Int
31+
32+
The Links REPL includes directives, which allow you to perform operations such
33+
as loading a file or showing the current type environment. To show all available
34+
directives, type ``@directives;``.
35+
36+
A useful directive is to load in a Links file, which populates the environment
37+
with all functions defined in the file. To see this, create a file called
38+
``helloWorld.links``::
39+
40+
fun sayHello() {
41+
print("Hello, world!")
42+
}
43+
44+
Now, from within a REPL, type ``@load "helloWorld.links";``, and then type
45+
``sayHello()``. You should see ``Hello, world!`` printed to the console::
46+
47+
_ _ __ _ _ __ ___
48+
/ | | | \ | | |/ / / ._\
49+
| | | | , \| | / \ \
50+
| |___| | |\ \ | |\ \ _\ \
51+
|_____|_|_| \__|_| \_|____/
52+
Welcome to Links version 0.9 (Burghmuirhead)
53+
links> @load "helloWorld.links";
54+
() : ()
55+
links>
56+
...... sayHello();
57+
Hello, world!() : ()
58+
links>
59+
60+
To exit the REPL, either press ``Ctrl-D`` or enter ``@quit;``.
61+
62+
Running files
63+
-------------
64+
65+
You are likely to want to run Links files from the command line, rather than
66+
from the REPL. Links files consist of a series of bindings, optionally followed
67+
by an expression. As an example, change ``helloWorld.links`` to::
68+
69+
fun sayHello() {
70+
print("Hello, world!")
71+
}
72+
sayHello()
73+
74+
Now, you can run the file from the command line::
75+
76+
$ linx helloWorld.links
77+
Hello, world!() : ()
78+
79+
Running the examples
80+
--------------------
81+
82+
As described in :ref:`install`, the environment variable ``$OPAM_SWITCH_PREFIX``
83+
points to the currently-active OPAM switch, and the example Links programs are
84+
installed into into ``$OPAM_SWITCH_PREFIX/share/links``.
85+
86+
To run the examples, run the following command at a terminal::
87+
88+
$ linx -m --path=$OPAM_SWITCH_PREFIX/share/links/examples:$OPAM_SWITCH_PREFIX/share/links/examples/games $OPAM_SWITCH_PREFIX/share/links/examples/webserver/examples-nodb.links
89+
90+
The ``-m`` flag enables modules, and the ``--path`` flag sets the path of where
91+
to look for Links files.
92+
93+
You should then be able to run the (non-database) examples by visiting
94+
``http://localhost:8080`` in a web browser.
95+
96+
97+
Setting up the database
98+
-----------------------
99+
100+
In this section, we will set up the database. We will concentrate on the
101+
``postgresql`` driver, but to use ``sqlite``, change ``postgresql`` to
102+
``sqlite``.
103+
104+
If you have not yet installed the ``links-postgresql`` library, you will need to
105+
do so; see :ref:`install`.
106+
107+
Configuration file
108+
~~~~~~~~~~~~~~~~~~
109+
110+
Next, we need to set up a configuration file which will contain the
111+
configuration options used to connect to the database. By default Links uses a
112+
configuration file located at ``$OPAM_SWITCH_PREFIX/etc/links/config``. Use the
113+
``--config=/custom/config/file`` flag to use a different configuration file.
114+
115+
To use database examples you need to add the database driver and connection
116+
string to the configuration file::
117+
118+
database_driver=postgresql
119+
database_args=localhost:5432:fred:password123
120+
121+
This tells Links to use the ``postgresql`` database driver; to connect to the
122+
SQL server on ``localhost`` running on port ``5432```; and to connect as user
123+
``fred`` with password ``password123``. If the server is running on
124+
``localhost``, or authentication does not require a password, then these two
125+
arguments can be omitted.
126+
127+
To use the above database string, the database user fred should exist. With
128+
Postgres, perhaps the easiest way to do this is to change ``fred`` to your Unix
129+
username, and thus no separate authentication is required.
130+
131+
Creating databases
132+
~~~~~~~~~~~~~~~~~~
133+
134+
If you are using postgres and you have tied your username to the database as
135+
described above, then you can initialise the database using the scripts in
136+
``examples/dbsetup``::
137+
138+
cd examples/dbsetup
139+
./createdbs
140+
./populatedbs
141+
142+
Otherwise, you can adapt them to your particular database set up.
143+
144+
The PostgreSQL data dumps for the larger databases (citations and
145+
dictionary) are not included in the main repository, but can be obtained from a
146+
`separate repository`_.
147+
148+
Running the database examples
149+
-----------------------------
150+
151+
You should then be able to run the examples using the database::
152+
153+
$ linx -m --path=$OPAM_SWITCH_PREFIX/share/links/examples:$OPAM_SWITCH_PREFIX/share/links/examples/games $OPAM_SWITCH_PREFIX/share/links/examples/webserver/examples.links
154+
155+
Adding the default examples path
156+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
157+
158+
For convenience, you may wish to add the default examples path to your
159+
configuration file::
160+
161+
path=$OPAM_SWITCH_PREFIX/share/links/examples:$OPAM_SWITCH_PREFIX/share/links/examples/games:$OPAM_SWITCH_PREFIX/share/links/examples/dictionary
162+
163+
You can then simply issue the following command to run the examples::
164+
165+
$ linx -m $OPAM_SWITCH_PREFIX/share/links/examples/webserver/examples.links
166+
167+
.. _separate repository: http://www.github.com/links-lang/links-data

‎install.rst

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,10 +1,14 @@
1+
.. _install:
2+
13
Installation
24
============
35

46
In this guide, we will get Links installed.
57
We recommend Links can be installed using the Opam_ tool, which is used to distribute OCaml
68
packages.
79

10+
Links is supported on Linux and Mac OSX. On Windows, we recommend using `Windows Subsystem for Linux`_.
11+
812
Installing OPAM
913
---------------
1014

@@ -61,12 +65,20 @@ PostgreSQL
6165
~~~~~~~~~~
6266

6367
Running::
68+
6469
opam install links-postgresql
6570

6671
will install the ``postgresql`` library, the required Links PostgreSQL driver,
6772
and recompile ``links`` to allow it to use the driver.
6873

6974

75+
Where next?
76+
~~~~~~~~~~~
77+
78+
Once you have installed Links, see the pages on :ref:`getting_started`.
79+
80+
7081
.. _Opam: https://opam.ocaml.org
7182
.. _OPAM installation pages: https://opam.ocaml.org/doc/Install.html
7283
.. _custom repository: https://launchpad.net/~ansible/+archive/ubuntu/bubblewrap
84+
.. _Windows Subsystem for Linux: https://docs.microsoft.com/en-us/windows/wsl/faq

0 commit comments

Comments
 (0)