I’d be interested to know what you found lacking in Quickstart — Dune documentation
I’m sure it could be improved.
2 Likes
The community is pretty eager to act on concrete feedback for improvement (within available bandwidth). But IMO this kind of general condemnation is not great for guiding improvement or for morale.
4 Likes
I have a git project with ocaml_experiments. The first problem was that I had no clue how to handle single-file examples. When I tried exercism, everything was set up for me. Looking at most of my commits, I would probably find that they were related to uncertainty about dune. I made initial commit on the 12th of October and did not progress far. It would be much easier if there was a simple example of project created with dune, using external libraries that I could easily expand.
Only last week I managed to get that:
Commits in my experiments folders indicate lack of understanding frustration and going in circles.
It took me ages to decipher documentation. If I judged the language similarly to a car and its acceleration from 0 to 60 miles, similarly I could judge the language, documentation and the ecosystem trying to find out how much it takes from 0 to snake game. So far OCaml gave me worst experience.
It is a known limitation of the human mind, so I am not surprised when I see dogmatism and a lack of understanding from experienced OCaml users. Similarly, some Haskellers lose the ability to explain Monads and other elements of the ecosystem.
I have a random collection of various links where some of them, to some extent, contradict one another. Partly because changes in the language and ecosystem, partly because people did not come up with a common way of doing OCaml that can be recommended to new users.
Somewhere in this thread there are comments of a programming lecturer, he may have to give you an idea what people struggle with. But if you do not have time to guide a new user and help him you will never understand our struggles. You forgot what it was like, or you are an expert, and OCaml is only for people like you.
Hello @Jacek_Podkanski,
My personal experience here is actually the opposite to your statement:
It is a known limitation of the human mind, so I am not surprised when I see dogmatism and a lack of understanding from experienced OCaml users.
and I read several of your posts/questions and actually I think that here all people were trying to help you. Honestly, my experience is that people try to understand the difficulties of beginners. Beginners also have to make the effort to calmly explain their difficulties.
Regarding: contradictory set of links that you have, you can share them for feedback, the people will be happy to discuss about it.
Partly because changes in the language and ecosystem, partly because people did not come up with a common way of doing OCaml that can be recommended to new users.
About this, it doesn’t seems to be specific of OCaml but the programming in general.
Well, then I must admit that I have those limitations as well. So I will ask calmly.
Why did it take me more than a month to sift through the difficult documentation and create example like ncforeign?
Why in other languages it would take me a day?
Why documentation in other languages has links to example repositories?
Why examples in OCaml libraries have different dune file and a noob can not translate those to a dune file that would be the result of editing dune file initialised with init?
What about project specific .ocamlinit or other ways of defining required libraries? How answering that is complicated by my lack of understanding of dune?
I hope my questions are reasonable.
PS.
Hope that will be the answer to my frustrations
Hello @Jacek_Podkanski
I don’t find useful to have here a long conversation, so I happy to discuss more via message. I think that the others users/developers here understand your frustrations, which others of us have gone through, but questioning the professionalism of the developers is not a way to reach a solution.
Why did it take me more than a month to sift through the difficult documentation and create example like ncforeign? Why in other languages it would take me a day?
I don’t know, but in the thread where you finally created your example ncforeign, others users gave you examples. I gave you like link to several examples in github, also I gave you the link to Real World Ocaml where the ncurses example is described offering my help with specific questions about it. Copy that code of the book and ask for specific help to have it running could solve this quicker. But anyway you solved, congrats.
Why examples in OCaml libraries have different dune file and a noob can not translate those to a dune file that would be the result of editing dune file initialized with init?
I don’t understand what you mean. Developers of libraries are free to edit their dune files according to their preferences/needs. This is fine.
What about project specific .ocamlinit or other ways of defining required libraries? How answering that is complicated by my lack of understanding of dune?
It is your choice to begin with dune. As I already commented, you can begin with ocamlfind/ocamlopt/ocaml to learn the language and then go to dune. Dune is not so straight forward, but it may be rewarding in long run.
I hope my questions are reasonable.
Your concerns are reasonable, I did not question that. But realize what the other user said to you:
I’d be interested to know what you found lacking in Quickstart — Dune documentation. I’m sure it could be improved. The community is pretty eager to act on concrete feedback for improvement.
and you replied with:
I am not surprised when I see dogmatism and a lack of understanding from experienced OCaml users.
Have a nice day.
1 Like
Where did I say that I question the professionalism? I only observed that some Haskellers lose the ability to explain Monads and similar may happen here, That has nothing to do with professionalism. When I show examples of what others did, it does not question your professionalism. Our communication has some frustrating imperfections, but again this does not question your professionalism.
I am thankful you made a real effort to reach out. When you observe the fact that we are going in circles, maybe this is the best I can do in the current circumstances and should go quiet.
I got a reply to my question that gave me 2 days of frustration and will try to see how far I can go with that.
Following the pretty long opam package install in Ubuntu of the ocsigen system, the demo app does not compile -
.opam/default/bin/js_of_ocaml: Error: missing dependency ‘caml_new_string’
Put me off right away.
1 Like
In none other language I have to browse source code on github instead of using go to definition in LSP recursively.
Still love OCaml.
2 Likes
I’m not sure to understand the example, because Format.formatter is abstract so even in another language you wouldn’t know its internals?
But maybe something which can help is hovering multiple times over the same value. It will expand the types more and more. This might avoid the need to jump recursively in some cases.
The issue is jumping to definition of a dependency and then trying to jump to definition to a transitive dependency doesn’t work.
3 Likes
I think OCaml is pretty awesome, and I switched from it to Standard ML (for hobby projects) mostly on a whim.
Usability is generally better in OCaml land. OCaml has a larger ecosystem, as well as high quality tools that have been refined over time by many people like an LSP and formatter, compared to SML’s good-but-more-nascent ones.
If I try to recall my pain points with OCaml, I think C FFI (trying to build bindings to a C library) with dune is the biggest that I experienced, but most of that (I think) was my own fault, as I knew less about the C ecosystem (tools like pkg-config) than I do now.
I’m not sure how easy/possible it is, but I would be happy to see the process of calling out to C (particularly with dune) made simpler.
With MLton"s C FFI (for example), it’s pretty easy to get by for someone inexperienced like me. To call GLFW functions, I had to:
- Create a shim in C (like this)
- Create a shim in SML (like this)
- Look up and copy the GCC command to link with GLFW in a C program, from their documentation
- Making small changes to that command telling MLton the link options to pass to the C compiler and passing the C shim files to MLton (link)
The step that makes this simple, I think, is (4). With OCaml/dune, one would need to translate the library’s link options to a dune stanza, which is complicated for someone who (like myself) knows C’s general syntax but not its “build ecosystem”.
I think this use case, where someone inexperienced with C wants to use a C library, is common (lots of people use SQLite knowing only higher level languages for example).
I would guess that there are generally more people in the OCaml community who would want to bind C libraries too, because of the smaller community here while mainstream languages have more people (= able to rely more on the work others have done).
2 Likes
A major gotcha for me, using emacs+merlin+dune, has been that merlin doesn’t always keep up with changes and reports incorrect errors. The only way to really understand what’s going on with your code is to code with a dune build --watch session alongside it (which is absolutely wonderful, by the way, but also seems to be essential to productivity and not mentioned very prominently) because the dune build on the command line is the only reliable source of feedback. Luckily it’s lightning quick! merlin seems to require a dune build that achieves… some unknown degree of success … to pick up changes in other files. This is now behavior I’m aware of so I don’t lose my mind, but when I first started with this setup I gave up many times because I didn’t know how to get a basic working environment going or whether my code was right. It made ocaml seem much harder than it is because merlin was giving me spurious errors.
The general solution seems to be that if the merlin error seems wrong, rm -rf _build && dune build --watch. Then revert the buffer and merlin sorts itself out. And if that doesn’t work, delete more and more code, saving the file, to let the dune build compile it successfully enough to shake something loose.
For example, today I tried the technique of splitting type definitions into a types file and including it in the mli and ml files of the module I’m developing, to avoid code duplication. e.g.
(* my_module_types.ml *)
type t = ...
(* my_module.mli *)
include module type of My_module_types
(* my_module.ml *)
include My_module_types
When updating one of the types in the types file, neither of the other files picked up the change. Only when I either a) produced a completely successful build in the accompanying dune build--watch session, or b) deleted enough code to produce a “successful enough” build, such that it shook something loose in merlin did it propagate the changes from the types file to the other files.
The only way I’m productive in OCaml is by keeping a dune build --watch or dune test --watch buffer open alongside my code, and know that that is the truth; merlin feedback is a bonus.
On that note - dune build --watch is so phenomenally good - instant compilation and feedback - that it’s one of OCaml’s killer features for me.
1 Like
Seems fairly prominent: Your First OCaml Program · OCaml Documentation
Before we dive in, note that you will typically want to use Dune’s watch mode to continually compile and optionally restart your program. This ensures that the language server has the freshest possible data about your project, so your editor support will be top-notch.
Do you have an idea to make it more prominent?
Thanks - you’re right that is quite prominent. I was looking at the dune Quick Start page, which doesn’t mention that. I haven’t gone through the getting started stuff on ocaml.org, at least not in quite a while. Maybe things are much clearer for a true newcomer now, who will probably start at ocaml.org and that page. I know the OCaml newcomer material has been rapidly improving the last couple years.
Oddly, even in watch mode and after deleting _build merlin doesn’t seem to see my shared types module at all - the include line says unbound module.
The solution to that problem is to delete from the downstream file any definitions that include or are below the error, save it, let --watch update things, and paste the code back in. That seems to shake loose whatever’s preventing merlin from acknowledging the included file.
As a newcomer to OCaml, I’ve been jotting down my pain points (and pleasant discoveries too!). Here’s a couple ones:
- Package management. opam is fairly simple to use, but having everything be in a global namespace by default is quite frustrating. It reminds me of the Python ecosystem using pip and virtualenv. I miss lockfiles and local dependencies by default. I also want multiple package versions to be possible.
- OCaml syntax is slightly difficult to understand. This isn’t that big a deal, I mostly picked it up after a day or two of writing code. But if you’re used to writing statement based languages with blocks, OCaml is not very intuitive. I wish I could toggle between Reason syntax and OCaml in my editor, so I can see how stuff would be written in a more mainstream syntax.
- Syntax errors. Syntax errors don’t give any explanation other than “syntax error”, a single line of code, and the location. Sometimes the error is actually before the given line. There also doesn’t seem to be much error recovery in the parser.
- Documentation. Libraries often don’t have a lot of documentation and what they do have is often out of date. The OCaml docs site is lovely though!
- IO. It’s not very clear how to print debug or write to files. I usually end up asking Claude for help. Tbh it might be nice to have some simple APIs for this like Rust’s
fs::read_to_stringorfs::write.
On the positive side:
- Type inference. It’s really nice not having to write out types when prototyping or editing code. You can make a change to a variable’s type and won’t need to edit a bunch of functions.
- Garbage Collection. This is a dumb one but coming from Rust it is genuinely nice being able to just use variables multiple times lol.
- Simplicity. I get the same vibe that I get from Go where the core language is fairly simple. The code does what it says and little is left implicit. I can spend more time writing code and less time writing the language if that makes sense.
- Interfaces. Interface files are a really nice way to think through your code and boundaries.
20 Likes
- Not a lot of University teach ocaml
- Not a lot of content in terms of video resources
- Not a lot of company uses ocaml
I think dune build @check builds just what is necessary for merlin / ocaml-lsp to work. you can add --watch to this request.
1 Like
As a newcomer myself, I’ve found In_channel and Out_channel to be great for basic IO.
4 Likes