-
Notifications
You must be signed in to change notification settings - Fork 0
Expand file tree
/
Copy pathcoding.html
More file actions
248 lines (202 loc) · 19.5 KB
/
coding.html
File metadata and controls
248 lines (202 loc) · 19.5 KB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
<!DOCTYPE HTML>
<!--
Solarize by TEMPLATED
templated.co @templatedco
Released for free under the Creative Commons Attribution 3.0 license (templated.co/license)
-->
<html>
<head>
<title>Functional Programming and Software Engineering</title>
<meta http-equiv="content-type" content="text/html; charset=utf-8" />
<meta name="description" content="" />
<meta name="keywords" content="" />
<!--[if lte IE 8]><script src="/pl/css/ie/html5shiv.js"></script><![endif]-->
<script src="/fpse/js/jquery.min.js"></script>
<script src="/fpse/js/jquery.dropotron.min.js"></script>
<script src="/fpse/js/skel.min.js"></script>
<script src="/fpse/js/skel-layers.min.js"></script>
<script src="/fpse/js/init.js"></script>
<noscript>
<link rel="stylesheet" href="/fpse/css/skel.css" />
<link rel="stylesheet" href="/fpse/css/style.css" />
</noscript>
<!--[if lte IE 8]><link rel="stylesheet" href="/fpse/css/ie/v8.css" /><![endif]-->
</head>
<body>
<!-- Header Wrapper -->
<div class="wrapper style1">
<!-- Header -->
<div id="header">
<div class="container">
<!-- Logo -->
<h1><a href="/fpse/index.html" id="logo">FPSE</a></h1>
<!-- Nav -->
<nav id="nav">
<ul>
<li><a href="/fpse/logistics.html">Logistics</a></li>
<li><a href="/fpse/dateline.html">Dateline</a></li> <!-- converted; don't edit .html edit .md -->
<li><a href="/fpse/coding.html">Coding</a>
<li><a href="">Assignments</a>
<ul class="menu">
<li><a href="/fpse/assignments/assignment1.html">Assignment 1</a></li>
<li><a href="/fpse/assignments/assignment2.html">Assignment 2</a></li>
<li><a href="/fpse/assignments/assignment3.html">Assignment 3</a></li>
<li><a href="/fpse/assignments/assignment4.html">Assignment 4</a></li>
<li><a href="/fpse/assignments/assignment5.html">Assignment 5</a></li>
<li><a href="/fpse/assignments/assignment6.html">Assignment 6</a></li>
<li><a href="/fpse/assignments/assignment7.html">Assignment 7</a></li>
<li><a href="/fpse/assignments/project.html">Project</a></li>
</ul></li> <li><a href="https://courselore.org/courses/1192943254">Q&A</a></li>
<li><a href="/fpse/contact.html">Contact Us</a></li>
</ul>
</nav>
</div>
</div>
<!-- close-out code before the standard footer .. use to glue in raw html. -->
</div>
<!-- Main -->
<div id="main" class="wrapper style4">
<!-- Content -->
<div id="content" class="container">
<section>
<link rel="stylesheet" href="/fpse/css/friendly.css" />
<meta charset="utf-8" />
<h2 id="ocaml-coding-information">OCaml Coding Information</h2>
<p>We are using <a href="https://ocaml.org">OCaml</a> version 5.3.0.</p>
<h3 id="installing-ocaml-530-and-associated-tools">Installing OCaml 5.3.0 and associated tools</h3>
<p>We require that you use the <a href="https://opam.ocaml.org">opam packaging system</a> for installing OCaml and its extensions. Once you get <code>opam</code> installed and working, everything else should be easy to install .. so the only hard part is the first step.</p>
<ul>
<li>For Linux or Mac see <a href="https://opam.ocaml.org/doc/Install.html">The OPAM install page</a> for install instructions.</li>
<li>For Mac users, the above requires <a href="https://brew.sh">Homebrew</a> (a package manager for Linux-ish libraries) so here is a more detailed suggestion of some copy/paste that should work.
<ul>
<li>Mac without homebrew installed:<code>/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"</code> will install Homebrew. Follow the instructions of things to copy/paste into your shell to complete the setup.</li>
<li>Mac with Homebrew already installed, or if you just installed as per above: run <code>brew update; brew install gpatch; brew install opam</code></li>
</ul>
</li>
<li>For Windows you should use WSL2, the Windows Subsystem for Linux. It creates a Linux-like system from within Windows.
<ul>
<li>Once you install <a href="https://learn.microsoft.com/en-us/windows/wsl/">WSL 2</a> you will be able to follow the Linux Ubuntu install instructions linked above.
<ul>
<li>Note that your WSL2 Ubuntu needs the C compiler and tools for the <code>opam</code> install to work; the following Linux shell command will get you those: <code>sudo apt install make m4 gcc zip unzip bubblewrap</code>.</li>
<li>You can still use your Windows install of VSCode to edit files by using the <a href="https://learn.microsoft.com/en-us/windows/wsl/tutorials/wsl-vscode">VSCode Remote WSL Extension</a> – it will connect the Windows editor to the underlying WSL2 subsystem. See below where VSCode is described for details on how to set this up.</li>
</ul>
</li>
<li>WSL2 has been working well for most people, but another option is to set up a Linux VM on your Windows box, and then set up a Linux install of OCaml within the VM. There are many good tutorials on how to build a Linux VM, <a href="https://www.lifewire.com/run-ubuntu-within-windows-virtualbox-2202098">here is one of them</a>. Once your virtual Linux box is set up, you can follow the <code>opam</code> Linux install instructions.</li>
</ul>
</li>
</ul>
<h3 id="initial-setup-of-opam">Initial setup of <code>opam</code></h3>
<p>You will need to run some terminal commands to set up the basics:</p>
<ol>
<li><code>opam init</code> will initialize OPAM (it should give a list of options 1/2/3/4/5, pick 1, <code>Yes update ~/.bash_profile</code> or something similar depending on your shell setup);</li>
<li>If you didn’t get that question or said to do nothing, you will need to add line, <code>eval $(opam env)</code>, to your <code>~/.bash_profile</code> or <code>~/.profile</code> or <code>~/.bashrc</code> shell init file (add to the first one of these files that exists already) as you would need to do that in every new terminal window otherwise. If you are using <code>zsh</code> on macs, add line <code>eval `opam env`</code> instead to your <code>~/.zshrc</code> file.</li>
<li><code>opam update</code> to make sure your <code>opam</code> is aware of all the versions of OCaml that are out there;</li>
<li><code>opam switch create 5.3.0</code> will build OCaml version 5.3.0.;</li>
<li>After a <code>opam switch</code> command it might instruct you to reset your path with some instructions like “Run <code>eval $(opam env --switch=5.3.0)</code> to update the current shell environment” – if you get that message, follow those instructions and copy/paste the in the command into the shell (if you are on a Mac you may be using <code>zsh</code>; replace the <code>$(...)</code> with back-quotes <code>`...`</code>).</li>
</ol>
<p>If you already have an earlier version of OCaml installed via <code>opam</code>, start on step 3. above to update to 5.3.0.</p>
<h4 id="required-opam-standard-packages">Required OPAM Standard packages</h4>
<p>Once you have <code>opam</code> and <code>ocaml</code> 5.3.0 installed, run the following <code>opam</code> command to install additional necessary packages for the class (just copy/paste these two lines into your shell):</p>
<div class="language-sh highlighter-rouge"><div class="highlight"><pre class="highlight"><code>opam <span class="nb">install </span>ocaml-lsp-server ocamlformat ocamlformat-rpc utop ounit2 base <span class="se">\</span>
base_quickcheck core async lwt ppx_jane ppx_deriving ppx_deriving_yojson bisect_ppx
</code></pre></div></div>
<p>Lastly, in order for the OCaml top loop to start up with some of these libraries already loaded, create or edit the file <code>~/.ocamlinit</code> to contain the lines below. The lines in this file are input to the top loop when it first starts. <code>topfind</code> really should be built-in, it allows you to load libraries. The <code>require</code> command is one thing <code>topfind</code> adds, here it is loading the <code>Core</code> libraries to replace the standard ones coming with OCaml. We will be using <code>Core</code> as they are improved versions.</p>
<div class="language-ocaml highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="o">#</span><span class="n">use</span> <span class="s2">"topfind"</span><span class="p">;;</span>
<span class="o">#</span><span class="n">require</span> <span class="s2">"ppx_jane"</span><span class="p">;;</span>
<span class="o">#</span><span class="n">require</span> <span class="s2">"core.top"</span><span class="p">;;</span>
<span class="k">open</span> <span class="nc">Core</span><span class="p">;;</span>
</code></pre></div></div>
<p>And here is a shell command which you can simply copy/paste to make the above file:</p>
<div class="language-sh highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="o">(</span><span class="nb">echo</span> <span class="s1">'#use "topfind";;'</span><span class="p">;</span> <span class="nb">echo</span><span class="p">;</span> <span class="nb">echo</span> <span class="s1">'#require "ppx_jane";;'</span><span class="p">;</span> <span class="nb">echo</span><span class="p">;</span> <span class="se">\</span>
<span class="nb">echo</span> <span class="s1">'#require "core.top";;'</span><span class="p">;</span> <span class="nb">echo</span><span class="p">;</span> <span class="nb">echo</span> <span class="s1">'open Core;;'</span><span class="o">)</span> <span class="o">></span>~/.ocamlinit
</code></pre></div></div>
<p>To test that your install works, type the shell command <code>utop</code> which will start up an interactive OCaml session (more later on that). Type <code>Fn.id;;</code> into the <code>utop</code> prompt followed by return, this is just a test to make sure the <code>Core</code> libraries were properly loaded. If you didn’t get an error message you are all good! Type control-D to quit <code>utop</code>.</p>
<h3 id="ocaml-documentation">OCaml Documentation</h3>
<p><a href="https://ocaml.org">ocaml.org</a> is the central repository of OCaml information.</p>
<h4 id="the-ocaml-manual">The OCaml Manual</h4>
<p>The OCaml manual is <a href="https://ocaml.org/manual/">here</a>.</p>
<ul>
<li>We will cover most of the topics in Part I Chapters 1 and 2 from the manual.</li>
<li>Manual Chapter 7 is the language reference where you can look up details if needed.</li>
<li>We will be covering a few topics in the <a href="https://ocaml.org/manual/extn.html">language extensions</a> chapter:
<ul>
<li><a href="https://ocaml.org/manual/locallyabstract.html">locally abstract types</a>,</li>
<li><a href="https://ocaml.org/manual/firstclassmodules.html">First-class modules</a>, and</li>
<li><a href="https://ocaml.org/manual/gadts.html">GADT’s</a>.</li>
</ul>
</li>
<li>Part III of the manual documents the tools, we will not be using much of this because third parties have improved on many of the tools and we will instead use those improved versions. See below in the Tools list where we give “our” list of tools.</li>
<li>Part IV describes the standard libraries but we are <em>not</em> using them so please <em>don’t</em> look here for <code>List</code>, <code>Map</code>, etc documentation. Note that if you Google up some OCaml library name you will likely get these libraries which will have subtly wrong documentation for us. We will primarily use Jane Street’s <code>Core</code> which replaces these with more modern versions, see the next item.</li>
</ul>
<h4 id="core">Core</h4>
<p><code>Core</code> is a complete rewrite of the standard libraries that come built in to OCaml. Think of it as a “more modern” version of lists, sets, hash tables, etc, with lots of little improvements in many places. <code>Core</code> itself an extension of <code>Base</code> and many modules in <code>Core</code> are directly lifted from <code>Base</code>.</p>
<ul>
<li><a href="https://ocaml.org/p/core/latest/doc/index.html">Core documentation</a></li>
<li>The <a href="https://dev.realworldocaml.org/index.html">Real World OCaml</a> book gives tutorial introductions to many of the <code>Core</code>/<code>Base</code> features.</li>
<li><strong>Important note</strong>: if you use a search engine to look up e.g. “OCaml Set” to see how the OCaml Set module is defined you will likely not get the <code>Core</code> version and it can be very confusing as it is similar. Even if you search “OCaml Set Core” you will likely get an outdated version of <code>Core.Set</code>. So, please <strong>bookmark the above link, and avoid countless hours of fruitless debugging because you are using the wrong library docs</strong>.</li>
</ul>
<h3 id="the-fpse-ocaml-toolbox">The FPSE OCaml Toolbox</h3>
<p>Here are all the tools we will be using. You are required to have a build for which all these tools work, and the above <code>opam</code> one-liner should install them all.</p>
<ul>
<li><a href="https://opam.ocaml.org"><code>opam</code></a> is the package management system. See above for install and setup instructions.</li>
<li><a href="https://ocaml.org/manual/comp.html"><code>ocamlc</code></a> is the standalone compiler which we will be invoking via the <code>dune</code> build tool.</li>
<li><a href="https://opam.ocaml.org/blog/about-utop/"><code>utop</code></a> is the read/eval/print loop. It is a replacement for the original <a href="https://ocaml.org/manual/toplevel.html"><code>ocaml</code></a> command, with many more features such as command history, replay, etc.</li>
<li><a href="https://opensource.janestreet.com/core/"><code>Core</code></a> was described above</li>
<li><a href="https://ocaml.github.io/odoc/odoc/index.html"><code>odoc</code></a> is the OCaml documentation generator, turning code comments into documentation webpages similar to JavaDoc etc.</li>
<li><a href="https://dune.build"><code>dune</code></a> is the build tool (think <code>make</code>) that we will be using.</li>
<li><a href="https://github.com/gildor478/ounit">OUnit</a> is the unit tester for OCaml. The opam package is called <code>ounit2</code> for obscure reasons.</li>
<li><a href="https://github.com/janestreet/ppx_jane"><code>ppx_jane</code></a> adds boilerplate functions to type definitions as well as many other macros. Unfortunately it is not documented, but <code>[@@deriving equal, compare, sexp]</code> for example will add equal and compare on a type, and to/from s-expression convertor functions.</li>
</ul>
<p>All of the above packages have documentation, but you may also want to try <a href="https://doc.sherlocode.com/">sherlodocs</a> where you can find documentation on all opam package details in one spot. For example typing <code>Core.Array</code> into the search will give all the documentation for the <code>Array</code> module in <code>Core</code>. Another documentation compilation is <a href="https://docs.ocaml.pro/about.html">The OCaml Documentation Hub</a>.</p>
<p>The above tools will be our “bread and butter”, we will be using them on many assignments. There are also a few specialized tools used on some specific assignments.</p>
<ul>
<li><a href="https://github.com/aantron/bisect_ppx">Bisect</a> will be used for code coverage.</li>
<li><a href="https://opensource.janestreet.com/base_quickcheck/">base_quickcheck</a> is a fuzz tester / automated test generator for OCaml.</li>
<li><a href="https://ocsigen.org/lwt/latest/api/Lwt">Lwt</a> is a non-preempting asychronous threads library.</li>
</ul>
<h3 id="development-environments-for-ocaml">Development Environments for OCaml</h3>
<p>We recommend VSCode since it has OCaml-specific features such as syntax highlighting, auto-indent, and lint analysis to make the coding process much smoother.</p>
<p><strong><a href="https://code.visualstudio.com">Visual Studio Code</a></strong></p>
<p>VSCode has very good OCaml support and is the “officially recommended editor”.</p>
<ul>
<li>
<p>To make VSCode OCaml-aware you will need to install the <strong>OCaml Platform</strong>. To install it, from the <code>View</code> menu select <code>Extensions</code>, and type OCaml in the search box and this extension will show up: select <strong>OCaml Platform</strong> from the list.</p>
</li>
<li>
<p>You can easily run a <code>utop</code> shell from within VSCode, just open up a shell from the <code>Terminal</code> menu and type <code>utop</code>.</p>
</li>
<li>
<p>If you are on Windows and using WSL2, you need to run Visual Studio “in WSL2 space” to get OCaml syntax highlighting and other nice features. See the <a href="https://docs.microsoft.com/en-us/windows/wsl/tutorials/wsl-vscode">Remote WSL Extension Docs</a> for details on how to set up the VSCode-WSL2 connection. If you are having trouble look at the <a href="https://docs.microsoft.com/en-us/windows/wsl/tutorials/wsl-vscode#additional-resources">Additional Resources</a> on that page. Once you have the above set up, install the OCaml Platform as described above and you should have syntax highlighting etc working.</p>
</li>
</ul>
<p><strong>vim</strong>: If you use <code>vim</code>, my condolances as it is woefully behind the times in spite of many band-aids added over the years. Still, if you have been brainwashed to believe it is good, type shell commands <code>opam install merlin user-setup</code> and <code>opam user-setup install</code> after doing the above default <code>opam</code> install to set up syntax highlighting, tab completion, displaying types, etc. See <a href="https://github.com/ocaml/merlin/blob/master/vim/merlin/doc/merlin.txt">here</a> for some dense documentation.</p>
<p><strong>emacs</strong>: See vim. You will need to also <code>opam install tuareg</code> to get emacs to work, and follow the instructions the install prints out.</p>
<h3 id="books">Books</h3>
<ul>
<li>The <a href="https://dev.realworldocaml.org/index.html">Real World OCaml</a> book has a fairly good overlap with what we will cover, and can be used as a supplementary resource.
<ul>
<li>It documents many of the extensions we will be using, the <code>Core</code> libraries in particular.</li>
</ul>
</li>
<li><a href="https://cs3110.github.io/textbook/cover.html">Cornell cs3110 book</a> is the online text for a somewhat-related course at Cornell. They have recently added many videos if you like watching videos to learn. Note that they are not using <code>Core</code>.</li>
<li><a href="https://johnwhitington.net/ocamlfromtheverybeginning/">OCaml from the very beginning</a> is a free online book.</li>
</ul>
<h3 id="coding-style">Coding Style</h3>
<ul>
<li>The <a href="http://pl.cs.jhu.edu/fpse/style-guide.html">FPSE Style Guide</a> is the standard we will adhere to in the class; it follows general best practices for modern OCaml. It will be expected of your code from Assignment 2 on.</li>
</ul>
<h3 id="example-worked-exercises">Example Worked Exercises</h3>
<p>One of the best ways to learn to write elegant OCaml is to study well-written OCaml code.</p>
<ul>
<li><a href="https://exercism.io/tracks/ocaml/exercises">Exercism OCaml Track</a> has a large set of programming problems to solve which have solutions by many other programmers as well. We will reference some of these examples in lecture.</li>
<li><a href="https://ocaml.org/problems">99 problems</a> solves 99 basic OCaml tasks.</li>
<li><a href="https://ocaml-sf.org/learn-ocaml-public/#activity%3Dexercises">Learn OCaml</a> has a large number of exercises to solve. The <a href="https://github.com/ocaml-sf/learn-ocaml-corpus/tree/master/exercises">solutions are online</a>.</li>
</ul>
</section>
</div>
</div>
<div id="copyright">
Web Design: TEMPLATED
</div>
</body>
</html>