We need to stop recommending Real World OCaml as introduction text

Community
1

The problem is its complete and unapologetic reliance on janestreet Base/Core/Async’s API, which requires additional setup by the user, and overrides the standard library in quite an opinionated manner. It’s adding lots of complication to a beginner’s learning journey I feel.

Don’t get me wrong, this is a phenomenal book with lots of valuable information, and being developed and written mainly thanks to janestreet means they have all the right to make it lean towards janestreet libraries. Just that this makes it less of an introduction to OCaml the language. They say just as much in the book, that this is not just an introduction to the language, but the language and specifically those libraries.

So many beginner questions about the language stem from confusion around what I like to call “Core-isms”; the book introduces its reader to relatively wider parts of the language right at the beginning than basic OCaml, of those I recall global open, named and optional arguments, first-class modules before even functors, ppx, locally abstract types vs universal quantifiers vs unification type variables, … these all have their interesting semantics that often result in repeated beginner questions.
And of course, onlookers have to be exposed right away to… beaten horses… in the community, such as “Stdlib is not adequate for general-purpose programming”, “polymorphic comparison is evil”, “exceptions vs option/result” (which also ties to the M-word), “OCaml is bad at polymorphic code because of value restriction” (so you should use modules soon and often), …
Additionally, the book really dives deep into many things about OCaml that you don’t often see in introductory text, like the runtime representation of OCaml values, the compiler frontend and backend, the compilation strategy, the garbage collector, ffi and binding, serialization, …

I think its role is better fulfilled as an intermediate book, for someone who’s already learned how OCaml works and would like to grow with it. I’d rather we rely on simpler, more self-contained introductory material for beginners.

That all said, I’d like to hear your opinions… Do you disagree? Do you see RWO as the most suitable introduction book for beginners? Also, are you familiar with other languages which have introductory material that also ties this strongly into an external ecosystem (Or is this something unique to us)?

23 Likes
2

Nah, its good. People should know about beaten horses. Polymorphic compare is bad and should be known about,ppx is the only way to reduce amount of senseless boilerplate. And about jane street libeary ecosystem: its great, its not just a replacement for a gaunt stdlib that comes with the compiler.

11 Likes
3

Welcome back! Opinion is definitely appreciated

All of these discussions are worth having don’t get me wrong, and part of one’s growth with the language is learning about its peculiarities. It just doesn’t seem like the right burden to have someone learning the ABCs of the language carry.

For me janestreet’s ecosystem brings with it lots of friction if you’re not 100% in on it. I’m not. Many things coming from there are sorely needed and often have high quality, I must admit, but I’ve had bad experiences too, with docs and with the way they architect their libraries (lots of aliasing lots of fcms lots of abstract interfaces…). ppxlib is a recent cause of pain for me. And that’s as someone who has some experience with the language.

One of my earliest memories with OCaml (I too was recommended RWO) was huge confusion around fcms vs functor syntax. In Stdlib you’d do module M = Map.Make(String) whereas in Base it’s let empty = Map.empty (module String). The distinction may be apparent to you today, but imagine yourself as a beginner with zero context on the language, the difference between module level functor application and value level function application, the subtleties of the syntax and where the module keyword should go, the whole type _ comparator = (module Comparator.S with type ...), these are all complexities you have to face when you don’t need to as a beginner.

A good guiding principle I’ve seen the designers of Swift mention before (I don’t remember when though, sorry!) was their emphasis on gradual exposure progressive disclosure of complexity. I think that is super important in an introductory material, as well as in language/api design in general.

14 Likes
4

I don’t think it’s even intended as a beginner’s book. I think it’s recommended to beginners because there are not many other options, especially if we restrict the search to more up-to-date books that show more realistic programs as examples and not only textbook-style code.

3 Likes
5

What other modern books can people recommend? I know that @dmbaturin wrote the following book, which uses the standard library: GitHub - dmbaturin/ocamlbook.org: A free (as in freedom) OCaml textbook. However, it is a work-in-progress.

When recommending a book, we need to understand the target audience. Someone totally new to programming, someone who’s used to imperative and object-oriented programming, but new to types functional programming, and someone who knows some functional programming would need different learning material. Do we want to focus on a specific audience, or have different books to cater to each of them?

2 Likes
6

For beginners there is

There’s a coursebook based on a course at Cornell (which also includes video lectures for each chapter) that has been highly recommended in the past:

There’s a nice introductory book with a more algorithmic focus, in French:

(This book is not available for free. However, the OCaml Foundation is planning to have it translated into English and making the translation available for free.)

The next two books are excellent, but sadly they are outdated, so they cannot be recommended to beginners. However, for readers with some experience, they are a gold mine.

The first one is my personal favorite (in French), straight from the horse’s mouth:

The second one is in English and is not available for free:

Cheers,
Nicolas

26 Likes
7

@hyphenrf said out loud what everyone else was thinking.

2 Likes
8

Lately I recommend the following as introductory material:

It has exercises too, which is the only way to really learn anything. Otherwise if you don’t actually try things out in the practice you may realize that you haven’t actually fully understood the material, or that the material hasn’t covered everything and there is a crucial piece missing that you have to discover for yourself. You don’t have to do all the exercises (some of them are more “algorithmic” exercises than about learning the language), but doing a few is recommended.

  • Chapters 1 through 11 from RealWorldOCaml. I still think it is useful, even though I’m not a fan of Core (the projects I work on day-to-day don’t use it, and there is considerable resistance in the community about projects depending on it). An appropriate warning that the book uses a separate library should be sufficient for newcomers though. It is more consistent than the standard library (e.g. datastructures have labeled arguments so you don’t have to learn that Map and Hashtbl take their arguments in different order), and discouraging the use of polymorphic comparison is good for learning (once you have a data structure more complex than a tuple or some records you really want to avoid polymorphic comparison, and if you learn this early on it, then it avoids making mistakes later).
    It has its downsides: reliance on ppxes, and as pointed out Map and Set being considerably more complicated to use (try writing a recursive data type that has a Map or Set, it requires writing it in a certain way with Map.M/Set.M for the provided sexp derivation to work without a compiler error that is not really explained anywhere…).
    However Base has improved a lot over the years, including the generated documentation (even though there are still completely undocumented functions in some modules), and in some sense the book complements the documentation.

I think this one is for those who are beginners to programming as well, and I can’t judge how well suited it’d be for that purpose (usually the people I recommend OCaml learning material for already know another programming language)

3 Likes
9

There aren’t that many books in OCaml unfortunately :frowning:

RWO is on my book shelf for now, as I’m going through “OCaml from the very beginning” first.

I’m glad I bought it! It’s a wonderful, wonderful book, so well put together.

Since I’m French, I also bought the book “programmer-avec-ocaml”, which I was very disappointed with. I stopped very early after rendering the Mandelbrot set section so I intend to get back to it at some point. But anyway, I couldn’t imagine any non-french speaking individual getting anything out of it.

From what I can gather, Core has introduced breaking changes to “make things better”, such as pushing the programmer into not raising exceptions, etc. so if this is the case, it looks like a good call to me and I’ll gladly read that book and see what techniques it recommends.

To me, this sounds a lot like the arguments in the Haskell community where no one can agree on how to make the standard library evolve because of breaking changes so it stays with its cruft, which is “subpar” by today’s standards.

1 Like
10

Has someone gone through the RWO book and ported all of the code using Jane St libraries to use other libraries instead?

5 Likes
11

I only know of GitHub - dkim/rwo-lwt: Lwt Translations of the Async Code Examples in Real World OCaml but it is not portimg all the code

1 Like
12

In an article, I kind of wrote some getting started in OCaml material.
I even said which parts of the online manual are essential, and which parts you can happily skip IIRC:

One problem with Core is that once you depend on it, it pulls the whole Jane Street ecosystem with it and you start to compile and install a crazy lot of things with opam (I am an impatient user of computers, so this it not OK with me).
Also, their interfaces are very “type heavy” and at least to my taste sometimes this impedes programmer productivity.

5 Likes
13

When I learned OCaml, the company I worked for recommended specific chapters of Real World OCaml. It is a good intro book, but beginners can stop after chapter 7 unless there’s something specific they want to know if later chapters.

Now that Base and Core are separate, is there any reason not to use Base?

14

There’s a nice introductory book with a more algorithmic focus, in French:

(This book is not available for free. However, the OCaml Foundation is planning to have it translated into English and making the translation available for free.)

Hi! Do you know if there is some progress on translating this book?

15

Hello, thanks for asking!

The first draft of the translation should be done within the next two weeks. Once complete, there will be a period of proof-reading and refreshing of the material by the authors. I suspect all this will take a couple of months at least.

I will make sure to announce the availability of the translation in this forum once it is ready.

Cheers,
Nicolas

6 Likes
16

I personally live without ppx because they complexify the build…

1 Like
17

same here. also leads to a ton less code in your trusted code base (as evaluated in remove ppx from mirage-tcpip by hannesm · Pull Request #505 · mirage/mirage-tcpip · GitHub)

2 Likes
18

I wonder if type classes is the feature that would make ppx no more needed.
I am really not a compiler guy so I am not following those things though.

19

I actually really like the RWO as a practical introduction book. It has examples for many operations that are common when someone starts and want to do real small operations. Writing a CLI, executing a http request, manipulating json, reading a file, … Transferring this knowledge to other libraries isn’t too complicated, especially once the vocabulary has been discovered. Being opinionated and up to date are qualities early in the learning process. Other resources tend to rely on a large number of libraries that must be combined together, usually without introducing all those libs, and provide outdated snippets.

My problem is more with the index of the book. It’s really non obvious for someone who is starting with ocaml, but not programing, that making a http request is in the Concurrent Programming with Async (What is concurrent programming? What is async?), that ppx (what is ppx?) are in error handling, that reading stdin is in Command-Line Parsing, that reading a file is in Handling JSON Data, … For someone who doesn’t want/need to read from first the last page, it is probably easier to navigate the book through google searches than through the home page of RWO.

6 Likes
20

it’s not, since there still is need for equivalents of ppx in haskell land (template haskell), and in rust land (macros), etc…
not even a basic deriving mechanism can be done without some form of staging support (or runtime type info)

3 Likes