I don’t use windows for development purposes, and have never tried building ocaml on that platform, but were I to want to do so I think @faldor20 has a reasonable point.
The best explanation about ocaml and windows is I suspect this one: ocaml/README.win32.adoc at trunk · ocaml/ocaml · GitHub . Many or indeed most open source developers (the title to this thread) would have no difficulty with this but morphing the topic to beginners, not used to unix-like tools, for them it is probably significantly confusing. To attract them, pre-compiled binaries are I suspect required, but that is something which appears about to come to an end.
My point isn’t really about getting help for my specific problems.
My point is if you want new people to come to your language an experience like mine really needs to be made near impossible. Even experienced developers just have better stuff to do than spend ages reading through various conflicting sources trying to sift nuggets of truth from the official guides. I mean I looked at all sorts of stuff and never even found that Github page. Even that comprehensive description doesn’t really say which is the “Recomended/best supported” way.
I mean look at Rust. Go to the website. "Hey your on windows This is how you should get setup:
Download this one exe, install rust, run ‘cargo init’ then "cargo run’ "
I understand that ocaml is/was very tied to UNIX but most of my trouble could have been easily fixed by an update to the ocaml website.
Anyway I shall move all further discussion to that new thread.
I understand, but these issues get solved one problem at a time, one person at a time. It’s not magic–we need to contribute somehow, even by just reporting an issue
I don’t know if you’ve seen the page on OCamlverse for Windows support. There’s also a quickstart page.
All I can say is, it’s been getting much better. Windows support isn’t here yet, but it seems to be on its way. A few years ago, the OCaml community didn’t even have a unified build tool.
I totally agree, I’m not expecting magic. I mostly was just trying to give a total outsiders perspective on the “windows ocaml onboarding experience” And I hope that once esy fix their compilation issue or opam 2.2 comes out with windows support I’ll be able to come back and give it a go.
@bluddy I think I did stumble onto their briefly after many other places, and I think it is the closest thing to the front-facing presence you would hope the language to have It certainly appears to be more up to date and concise than ocaml.org.
My only comment on that would be that it would be nice to explain what they mean by “some packages won’t work on esy” that is a deeply nebulous statement that doesn’t actually help me decide if esy is worth trying or not.
I guess in some ways I’m not that surprised, somehow it seems like in a lot of cases language age is inversely proportional to tooling quality I suppose people in days of yore were just to hardcore for all that fluff.
As someone new to OCaml (coming from Python) I did not find it too hard to get set up.
I find the tooling has been surprisingly good and usable out of the box (opam, dune, the VS Code plugin) as a macOS/homebrew user.
The main issue I have is lack of a culture of documentation from library authors.
A lot of libraries only have “api docs” style documentation, i.e. an index of functions and types. I assume there is some tooling that makes this easy to generate directly from source code, pulling in text from comments and formatting as html, since it seems like most libraries just publish the auto-generated docs and stop there.
Unfortunately this is the least useful type of documentation. It really only provides info that is already available via the IDE.
I would say the majority of OCaml libraries I’ve come into contact with could be improved just by showing more usage examples in the docs.
With Python libs their documentation tends to have the opposite flavour - I have the impression that many are published without “api docs” at all, but there will at least be some usage examples on the github readme - usually aimed at showing off how nice and easy the library is. If I need to dig into all the functions and arguments etc I can always just look at the source code.
I think the Diátaxis article is really useful guidance.
I’d been tempted to comment on the other thread when I saw it before. It seemed to end up discussing ways to extend odoc tooling, as if the problem is that it’s “too hard” to write docs and a technical solution could help that.
But I almost feel like the problem may be the opposite - the tooling to make the “least helpful” kind of docs is already too easy.
The default docs tooling in Python is Sphinx, which basically asks you to sit down and write a bunch of .rst files from scratch as if authoring a technical manual. It’s a bit of a pain (to the extent that personally I often just write an elaborate readme instead) but it’s also an approach to docs that requires you to think about how and what to communicate.
I’m not convinced there are technical solutions to this situation. I’m not sure what it needs - maybe for authors of popular or key-stone libraries in the OCaml community to set an example?
IMO the issue is not tooling, but that developers simply tend not to write full docs, taking a “shortcut” sort of approach, and prematurely considering work to be done.
There are of course exceptions, such as Dune, among others.
The numerous problems with the ecosystem make OCaml a tough sell to new developers:
You can’t read the documentation of opam modules without installing them, because it isn’t available online. I’m not aware of any other major language where it’s the case.
The standard library situation is confusing. Which one am I supposed to use?
Windows support.
OCaml is being developed behind the closed doors. There is a public github repository which takes PRs, which I really appreciate, but the discussions about the development of the language are hidden from the public. For example, did you know that flambda2 is a thing that exists? Compare this to Rust (internals forum), Python (“committers” and “core development” subforums), Perl (perl5-porters) etc.
The situation with Jane Street libraries is even worse. They don’t even have a public git repository!
There’s also a problem with lack of libraries, but that’s expected of a non-mainstream language, so I didn’t include that in the above list.
What you want, this is by design. Go with the official one if you really don’t know.
Indeed, but see other recent threads.
This is an open-source project which by definition is antithetical to closed doors, and basically all the things you spoke about can be viewed by following Github and this forum.
JaneStreet owe OCaml community nothing, it’s bonus to be able to access their open-sourced projects. starting point
OCaml is not being developed behind closed doors. First, Flambda2 is an internal project of Janestreet that has not been discussed yet, and not some kind of secret future development. It you want to judge the openness of OCaml’s development it is better to look at OCaml multicore. Similarly, it is true that there is some maintainers-only discussion channels and meetings, but there are mostly here for the sake of coordination. Honestly, if you don’t see much public ongoing discussion on a subject, it is more probable than there is simply no on-going discussion at all: most OCaml developers and maintainers are busy people and not working full time on OCaml.
Thanks, I somehow missed the announcement. I’m really glad this was created! It’s still a shame that so many modules don’t have a proper documentation, though…
I never said they owe us anything, but it doesn’t change the fact that it’s a problem.
Maybe it’s because I have too high expectations (see the projects that I’ve linked in my first post), but that doesn’t really seem “open” to me. I’m not saying that the current situation is terrible, as I said, I’m glad that there’s a public github repository, I just feel this could be improved.
I think, if I understand this correctly, that you mean that the development of Jane Street’s open source libraries doesn’t “happen in” the public GitHub repos, is that right? Jane Street uses a monorepo internally, so changes to Core, Async, and so on all happen mixed in the same repo with changes to other non-public libraries. As a result, commits to the repos on GitHub just correspond to some internal version numbers but not to actual commits in our internal repo (which uses hg, by the way).
External contributions to our libraries (issues, PRs, etc.) are absolutely welcome! There are certainly a ton of things that could be improved with better tooling (and our response times are, to put it mildly, not great), and we are continuing to try to make this workflow better, both for contributors on GitHub as well as internally (for example, we now have some automation for importing GitHub PRs and issues into our code review system for employees to review).
I often see this comment being made when people compare Rust to other communities. Different projects have different development styles. There is no perfect one-size-fits-all style. Rust’s management structure also takes an enormous amount of work. As was mentioned before, a lot of OCaml developers aren’t doing it as their full-time jobs.
On Rust’s openness, I enjoyed this story on Dave Herman’s role during Rust’s early days, in particular their belief that openness would be essential to its success and even survival when Mozilla’s management could decide to pull the plug anytime. It shows openness as not something that you can only afford once you are big enough, but that you can do to grow when you are just a couple of people.
Regarding the standard library situation, I wish that the role of the standard library in preventing the fragmentation in incompatible dialects was better recognised (see Stroustrup’s papers on the history of C++ where fighting against fragmentation is a recurring leitmotiv, which is another place where you can read rational explanations for the success of a language).
Might it be a good idea to expose the aforementioned Janestreet monorepo on GitHub (minus any proprietary parts) so we can see the flow of commits?
This would increases the feeling of “openness” and “community” (admittedly slightly vague concepts but important). Right now I feel a closer link to more “public” libraries (e.g. lwt) because discussions, commits etc take place in the open.
A Janestreet monorepo on GitHub would increase the probability of external contributions as other companies can follow development in a more logical fashion. More external eyes may lead to a more reliable internal codebase. In fact it is amazing how much benefit companies like Google have derived by fully exposing (some) of the software they use internally to the world (e.g. the Golang compiler is a good example).
You don’t necessarily need to expose the ticketing system (though that would also be amazing) but the commits should make more sense. Right now the GitHub commits seem to have absolutely no attached context (and it seems that many commits are often squashed into a single one).
A lot of big companies like Microsoft, Facebook, Google etc. seem to be doing this kind of open development on various projects. There are benefits to this approach which I’m sure the Janestreet folks already know.
The OCaml community is grateful for all the contributions Janestreet is making – no question about it. But I’m wondering if moving to a more open style of development might be a win-win for Janestreet and the wider OCaml userbase.
Or is it that it is extremely difficult to disentangle the private and open-source parts in your monorepo?
won’t compile packages because of symlink errors issue-1315
This is a common problem, not esy related at all, if you’re untaring stuff with invalid symlink on Windows it happens.
And maybe I should run it as admin?? At least according to some github issues, but also maybe that isn’t important anymore?
That was fixed on the latest release, the setup on windows is just install and enable developer mode, again this problem also exists on any other platform that uses symlinks on Windows, I myself have hit that in the past when doing JS and someone was using node symlink.
Also a personal tip, disable windows defender, on any platform where native binaries are generated, windows defender kills performance. And you will feel this on esy as we have a clean room approach of building everything from scratch.
Also you can just use WSL if you don’t mind generating binaries to Windows.
There are a few projects where Jane Street has done development primarily on Github: Dune and Ppxlib are good examples of this. This makes sense in part because these projects involve intense collaboration with outside developers.
Similarly, our work on the compiler is all done on Github, either on various forks of the regular OCaml repo, or on the flambda-backend repo, where Flambda2 and other back-end features are being developed.
I don’t think it’s really any less open than the general compiler development process, which indeed mostly hosts its discussions on closed forums. Even so, PRs are a pretty good way to follow development there.
For packages exported from our monorepo, we’re not likely to ever do a commit-by-commit export, because we vet outgoing pushes before they go out, and doing it commit by commit would be very painful. The current process happens about once a week, which isn’t perfect, but seems like a reasonable compromise to us.
We do have plans to export a usable monorepo of the data in our current open-source repos, but the goal there is mostly ease of use. We hope it will make development easier for external contributors, among other benefits.
