OCaml engineering field guide

guide

#1

We need a document or book about OCaml engineering best practices.

Topics that would be good to cover:

  • Toolchain setup
    • Editor and support tooling for the editor, e.g. Merlin and build
      error reporting
    • Project management including multiple projects with dependencies
      among each other
  • Compatibility
    • How to maintain source compatiblity (e.g. with SemVer and what OCaml
      practices are necessary for SemVer or a best effort approximation of
      it)
    • How to achieve binary compatibility or how to at least deploy
      binaries to end users
    • How to cross-compile
  • Overview of essential application libraries. These are the things you
    need if you want to convince a business that OCaml is a viable
    application programming language
    • Concurrency with Lwt
    • How to write a web server
    • How to write a webapp frontend with BuckleScript/Reason
    • How to write a GUI with Lablgtk
    • How to connect to and interact with popular databases
  • How to deploy:
    • Native binary/bytecode/JavaScript
    • Docker image
    • (Perhaps) unikernel image

Would appreciate thoughts and ideas here.


#2

ocaml.org seems like an ideal place for this guide/content to live.


#3

I disagree.

More online resources is always great (I certainly wouldn’t mind having more books), but there’s already awesome-ocam.

I think that what the community needs is way more blog writers. People that know “some OCaml” and are vocal and opinionated enough to spread their knowledge. Ideally, you would be able to look up “Concurrency with Lwt” on google and find more than auto-generated docs and forum questions.


#4

Thanks for the pointer Gerson. Awesome-ocaml is indeed a very nice list, but it’s not a guide. That is, it’s not really designed to give you an idea of what’s considered to be engineering best practices in OCaml, and an overview of how to accomplish certain common tasks. It’s more focused on what libraries and tools exist in the ecosystem. Two different viewpoints.

As for bloggers, that would indeed be very nice, but it wouldn’t really alleviate the confusion of newcomers trying to figure out how to do something. A central source of documentation would.


#5

That is a very interesting list of topics, @yawaramin!

If I remember correctly http://ocaml.org/learn/tutorials/ is saying this on top:

Your Help is Needed

Many of the tutorials below need updating and tutorials on many new topics are needed. Please contribute by visiting this project’s repo on GitHub; you may use the issue tracker there to request or offer new tutorials. Thanks!

So perhaps we could direct some of these there instead of creating a new portal?

Or, we could build a new wiki, such as https://wiki.haskell.org/Introduction.

Both of these approaches can use community contributions, but we might need to measure which are friendlier, creating PRs for ocaml.org tutorials or creating and editing a wiki page.


#6

I totally agree, guides and tutorials should be centralised as much as possible. I should clarify that I want to avoid creating new OCaml portals–if at all possible :slight_smile:


#7

OCaml Planet offers a neat way for blog articles to be “centralised” in a decentralised way. @gersonmoraes @yawaramin

Blog articles tend to be more analytical on the topic they focus and at times they can offer usefully alternative narratives. They should be a nice addition to some base documentation on OCaml.org.


#8

I think this would be definitely useful. I am creating the internal version of this for our engineers. I would be interesteded working with you on this one too.


#9

Fantastic, I’d love to collaborate. Would you be open to working on a GitHub repo?


#10

Totally, I have some preliminary stuff for Reason (because most of our devs are frontend) and some experience building OCaml apps for backends. I would be more than happy to work with you on this guide.


#11

Hello, I’ve created https://github.com/yawaramin/ocaml-field-guide , let me know your GitHub username and I’ll add you as a collaborator. Cheers