From 3cc0738fd350033742e6c5aeb6648ee1add12a91 Mon Sep 17 00:00:00 2001 From: Patrick Ferris Date: Sat, 15 Jan 2022 11:03:50 +0000 Subject: [PATCH 1/3] Regenerate ood for best practices change --- src/ocamlorg_data/workflow.ml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/ocamlorg_data/workflow.ml b/src/ocamlorg_data/workflow.ml index aabc48d297..bb04812583 100644 --- a/src/ocamlorg_data/workflow.ml +++ b/src/ocamlorg_data/workflow.ml @@ -18,8 +18,8 @@ let all = }; { title = "Updating dependencies" - ; body_md = "\n> **TL;DR**\n> \n> If the project generates the `*.opam` file from the `dune-project`, add the dependency in the `package` stanza and run `opam install . --deps-only`.\n> If the project does not generate the `*.opam` file, add the dependency in the `*.opam` file and run `opam install . --deps-only`.\nTo avoid duplicating the project configuration into multiple files, Dune allows to generate the `*.opam` file of the project from the \npackage definitions in `dune-project` when adding the `(generate_opam_files true)` stanza.\n\nHowever, opam remains a central piece of the ecosystem and it's very likely that you will have to work with `*.opam` files at some point,\nso we don't take a stance on wether you should specify your dependencies in the `*.opam` file or in `dune-project`.\n\nIf the project generates the opam file from the `dune-project` (you can tell by the line `# This file is generated by dune, edit dune-project instead` at the top of the `*.opam` file), you can add your dependencies in the `dune-project` in the appropriate `package` stanza. It should look like this:\n\n```dune\n(package\n (name demo)\n (synopsis \"A short, but powerful statement about your project\")\n (description \"An complete and exhaustive description everything your project does.\")\n (depends\n (ocaml\n (>= 4.08.0))\n dune\n (alcotest :with-test)\n (odoc :with-doc)))\n```\n\nOnce you have added your dependency, you can build your project with `dune build` which will re-generate the `*.opam` files.\n\nIf the `*.opam` files are not generated, you can add the dependencies in them directly, in the `depends` field. If should look like this:\n\n\n```opam\nopam-version: \"2.0\"\nsynopsis: \"A short, but powerful statement about your project\"\ndescription: \"An complete and exhaustive description everything your project does.\"\ndepends: [\n \"ocaml\" {>= \"4.08.0\"}\n \"dune\"\n \"alcotest\" {with-test}\n \"odoc\" {with-doc}\n]\nbuild: [\n [\"dune\" \"subst\"] {pinned}\n [\n \"dune\"\n \"build\"\n \"-p\"\n name\n \"-j\"\n jobs\n \"@install\"\n \"@runtest\" {with-test}\n \"@doc\" {with-doc}\n ]\n]\n```\n\nEither way, once you have added your dependency in the appropriate file, you can run `opam install . --deps-only` to update your current switch's dependencies.\n" - ; body_html = "
\n

TL;DR

\n

If the project generates the *.opam file from the dune-project, add the dependency in the package stanza and run opam install . --deps-only.\nIf the project does not generate the *.opam file, add the dependency in the *.opam file and run opam install . --deps-only.\nTo avoid duplicating the project configuration into multiple files, Dune allows to generate the *.opam file of the project from the\npackage definitions in dune-project when adding the (generate_opam_files true) stanza.

\n
\n

However, opam remains a central piece of the ecosystem and it's very likely that you will have to work with *.opam files at some point,\nso we don't take a stance on wether you should specify your dependencies in the *.opam file or in dune-project.

\n

If the project generates the opam file from the dune-project (you can tell by the line # This file is generated by dune, edit dune-project instead at the top of the *.opam file), you can add your dependencies in the dune-project in the appropriate package stanza. It should look like this:

\n
(package\n (name demo)\n (synopsis \"A short, but powerful statement about your project\")\n (description \"An complete and exhaustive description everything your project does.\")\n (depends\n  (ocaml\n   (>= 4.08.0))\n  dune\n  (alcotest :with-test)\n  (odoc :with-doc)))\n

Once you have added your dependency, you can build your project with dune build which will re-generate the *.opam files.

\n

If the *.opam files are not generated, you can add the dependencies in them directly, in the depends field. If should look like this:

\n
opam-version: \"2.0\"\nsynopsis: \"A short, but powerful statement about your project\"\ndescription: \"An complete and exhaustive description everything your project does.\"\ndepends: [\n  \"ocaml\" {>= \"4.08.0\"}\n  \"dune\"\n  \"alcotest\" {with-test}\n  \"odoc\" {with-doc}\n]\nbuild: [\n  [\"dune\" \"subst\"] {pinned}\n  [\n    \"dune\"\n    \"build\"\n    \"-p\"\n    name\n    \"-j\"\n    jobs\n    \"@install\"\n    \"@runtest\" {with-test}\n    \"@doc\" {with-doc}\n  ]\n]\n

Either way, once you have added your dependency in the appropriate file, you can run opam install . --deps-only to update your current switch's dependencies.

\n" + ; body_md = "\n> **TL;DR**\n> \n> If the project generates the `*.opam` file from the `dune-project`, add the dependency in the `package` stanza and run `opam install . --deps-only`.\n> If the project does not generate the `*.opam` file, add the dependency in the `*.opam` file and run `opam install . --deps-only`.\nTo avoid duplicating the project configuration into multiple files, Dune allows to generate the `*.opam` file of the project from the \npackage definitions in `dune-project` when adding the `(generate_opam_files true)` stanza.\n\nHowever, opam remains a central piece of the ecosystem and it's very likely that you will have to work with `*.opam` files at some point,\nso we don't take a stance on wether you should specify your dependencies in the `*.opam` file or in `dune-project`.\n\nIf the project generates the opam file from the `dune-project` (you can tell by the line `# This file is generated by dune, edit dune-project instead` at the top of the `*.opam` file), you can add your dependencies in the `dune-project` in the appropriate `package` stanza. It should look like this:\n\n```dune\n(package\n (name demo)\n (synopsis \"A short, but powerful statement about your project\")\n (description \"An complete and exhaustive description everything your project does.\")\n (depends\n (ocaml\n (>= 4.08.0))\n dune\n (alcotest :with-test)\n (odoc :with-doc)))\n```\n\nOnce you have added your dependency, you can build your project with `dune build` which will re-generate the `*.opam` files.\n\nIf the `*.opam` files are not generated, you can add the dependencies in them directly, in the `depends` field. If should look like this:\n\n\n```opam\nopam-version: \"2.0\"\nsynopsis: \"A short, but powerful statement about your project\"\ndescription: \"An complete and exhaustive description everything your project does.\"\ndepends: [\n \"ocaml\" {>= \"4.08.0\"}\n \"dune\"\n \"alcotest\" {with-test}\n \"odoc\" {with-doc}\n]\nbuild: [\n [\"dune\" \"subst\"] {pinned}\n [\n \"dune\"\n \"build\"\n \"-p\"\n name\n \"-j\"\n jobs\n \"@install\"\n \"@runtest\" {with-test}\n \"@doc\" {with-doc}\n ]\n]\n```\n\nEither way, once you have added your dependency in the appropriate file, you can run `opam install . --deps-only` to update your current switch dependencies.\n" + ; body_html = "
\n

TL;DR

\n

If the project generates the *.opam file from the dune-project, add the dependency in the package stanza and run opam install . --deps-only.\nIf the project does not generate the *.opam file, add the dependency in the *.opam file and run opam install . --deps-only.\nTo avoid duplicating the project configuration into multiple files, Dune allows to generate the *.opam file of the project from the\npackage definitions in dune-project when adding the (generate_opam_files true) stanza.

\n
\n

However, opam remains a central piece of the ecosystem and it's very likely that you will have to work with *.opam files at some point,\nso we don't take a stance on wether you should specify your dependencies in the *.opam file or in dune-project.

\n

If the project generates the opam file from the dune-project (you can tell by the line # This file is generated by dune, edit dune-project instead at the top of the *.opam file), you can add your dependencies in the dune-project in the appropriate package stanza. It should look like this:

\n
(package\n (name demo)\n (synopsis \"A short, but powerful statement about your project\")\n (description \"An complete and exhaustive description everything your project does.\")\n (depends\n  (ocaml\n   (>= 4.08.0))\n  dune\n  (alcotest :with-test)\n  (odoc :with-doc)))\n

Once you have added your dependency, you can build your project with dune build which will re-generate the *.opam files.

\n

If the *.opam files are not generated, you can add the dependencies in them directly, in the depends field. If should look like this:

\n
opam-version: \"2.0\"\nsynopsis: \"A short, but powerful statement about your project\"\ndescription: \"An complete and exhaustive description everything your project does.\"\ndepends: [\n  \"ocaml\" {>= \"4.08.0\"}\n  \"dune\"\n  \"alcotest\" {with-test}\n  \"odoc\" {with-doc}\n]\nbuild: [\n  [\"dune\" \"subst\"] {pinned}\n  [\n    \"dune\"\n    \"build\"\n    \"-p\"\n    name\n    \"-j\"\n    jobs\n    \"@install\"\n    \"@runtest\" {with-test}\n    \"@doc\" {with-doc}\n  ]\n]\n

Either way, once you have added your dependency in the appropriate file, you can run opam install . --deps-only to update your current switch dependencies.

\n" }; { title = "Updating development dependencies" From d815ef74a63a1c31aabdc171c88c2db54cf3a6a5 Mon Sep 17 00:00:00 2001 From: Patrick Ferris Date: Sat, 15 Jan 2022 11:04:05 +0000 Subject: [PATCH 2/3] Add WSL2 information --- data/tutorials/en/000_up_and_running.md | 10 ++++++---- src/ocamlorg_data/tutorial.ml | 18 ++++++++++-------- src/ocamlorg_frontend/url.ml | 2 ++ src/ocamlorg_web/lib/redirection.ml | 9 +++++++-- src/ocamlorg_web/lib/router.ml | 1 + 5 files changed, 26 insertions(+), 14 deletions(-) diff --git a/data/tutorials/en/000_up_and_running.md b/data/tutorials/en/000_up_and_running.md index 7763c025ed..d64c2901bd 100644 --- a/data/tutorials/en/000_up_and_running.md +++ b/data/tutorials/en/000_up_and_running.md @@ -66,10 +66,10 @@ sh <(curl -sL https://raw.githubusercontent.com/ocaml/opam/master/shell/install. ### For Windows -We use the [OCaml for Windows](https://fdopen.github.io/opam-repository-mingw/) -installer which comes in 32bit and 64bit versions. This installer gives you -opam and OCaml installations all in one go. It is used from within a Cygwin -environment, but the executables produced have no dependency on Cygwin at all. +OCaml on Windows is still a work in progress. In the meantime, if you only +need to *run* OCaml programs on a Windows machine, then the simplest solution is to use the Windows Subsystem for Linux 2 (WSL2). WSL2 is a feature that allows Linux programs to run directly on Windows. WSL2 is substantially easier and faster to use than WSL1. Microsoft have comprehensive installation steps for [setting up WSL2](https://docs.microsoft.com/en-us/windows/wsl/install-win10). + +On the other hand, if you need Windows binaries then you will have to use the [OCaml for Windows](https://fdopen.github.io/opam-repository-mingw/) installer which comes in 32bit and 64bit versions. This installer gives you opam and OCaml installations all in one go. It is used from within a Cygwin environment, but the executables produced have no dependency on Cygwin at all. For a more comprehensive update on the state of OCaml on Windows, see the [OCaml on Windows](/platform/ocaml_on_windows.html) page on the old version of the site. ## The OCaml top level @@ -204,6 +204,8 @@ from the list. Now, help is available by hovering over symbols in your program: ![Visual Studio Code](/media/tutorials/vscode.png "") +**On Windows using WSL2** you will remotely connect to your WSL2 instance from Visual Studio Code. Microsoft have a [useful blog post](https://code.visualstudio.com/blogs/2019/09/03/wsl2) covering getting WSL2 and Visual Studio Code connected. + **On Windows**, we must launch Visual Studio Code from within the Cygwin window, rather than by clicking on its icon (otherwise, the language server will not be found): diff --git a/src/ocamlorg_data/tutorial.ml b/src/ocamlorg_data/tutorial.ml index bf34f0bf64..7acca90f83 100644 --- a/src/ocamlorg_data/tutorial.ml +++ b/src/ocamlorg_data/tutorial.ml @@ -86,10 +86,10 @@ sh <(curl -sL https://raw.githubusercontent.com/ocaml/opam/master/shell/install. ### For Windows -We use the [OCaml for Windows](https://fdopen.github.io/opam-repository-mingw/) -installer which comes in 32bit and 64bit versions. This installer gives you -opam and OCaml installations all in one go. It is used from within a Cygwin -environment, but the executables produced have no dependency on Cygwin at all. +OCaml on Windows is still a work in progress. In the meantime, if you only +need to *run* OCaml programs on a Windows machine, then the simplest solution is to use the Windows Subsystem for Linux 2 (WSL2). WSL2 is a feature that allows Linux programs to run directly on Windows. WSL2 is substantially easier and faster to use than WSL1. Microsoft have comprehensive installation steps for [setting up WSL2](https://docs.microsoft.com/en-us/windows/wsl/install-win10). + +On the other hand, if you need Windows binaries then you will have to use the [OCaml for Windows](https://fdopen.github.io/opam-repository-mingw/) installer which comes in 32bit and 64bit versions. This installer gives you opam and OCaml installations all in one go. It is used from within a Cygwin environment, but the executables produced have no dependency on Cygwin at all. For a more comprehensive update on the state of OCaml on Windows, see the [OCaml on Windows](/platform/ocaml_on_windows.html) page on the old version of the site. ## The OCaml top level @@ -224,6 +224,8 @@ from the list. Now, help is available by hovering over symbols in your program: ![Visual Studio Code](/media/tutorials/vscode.png "") +**On Windows using WSL2** you will remotely connect to your WSL2 instance from Visual Studio Code. Microsoft have a [useful blog post](https://code.visualstudio.com/blogs/2019/09/03/wsl2) covering getting WSL2 and Visual Studio Code connected. + **On Windows**, we must launch Visual Studio Code from within the Cygwin window, rather than by clicking on its icon (otherwise, the language server will not be found): @@ -312,10 +314,9 @@ available:

sh <(curl -sL https://raw.githubusercontent.com/ocaml/opam/master/shell/install.sh)

For Windows

-

We use the OCaml for Windows -installer which comes in 32bit and 64bit versions. This installer gives you -opam and OCaml installations all in one go. It is used from within a Cygwin -environment, but the executables produced have no dependency on Cygwin at all.

+

OCaml on Windows is still a work in progress. In the meantime, if you only +need to run OCaml programs on a Windows machine, then the simplest solution is to use the Windows Subsystem for Linux 2 (WSL2). WSL2 is a feature that allows Linux programs to run directly on Windows. WSL2 is substantially easier and faster to use than WSL1. Microsoft have comprehensive installation steps for setting up WSL2.

+

On the other hand, if you need Windows binaries then you will have to use the OCaml for Windows installer which comes in 32bit and 64bit versions. This installer gives you opam and OCaml installations all in one go. It is used from within a Cygwin environment, but the executables produced have no dependency on Cygwin at all. For a more comprehensive update on the state of OCaml on Windows, see the OCaml on Windows page on the old version of the site.

The OCaml top level

OCaml comes with two compilers: for native code, and for byte code. We shall use one of those in a moment. But first, let's use OCaml's top level (sometimes @@ -410,6 +411,7 @@ Studio Marketplace.

toolchain in use: pick OCaml the version of OCaml you are using, e.g. 4.11.1 from the list. Now, help is available by hovering over symbols in your program:

Visual Studio Code

+

On Windows using WSL2 you will remotely connect to your WSL2 instance from Visual Studio Code. Microsoft have a useful blog post covering getting WSL2 and Visual Studio Code connected.

On Windows, we must launch Visual Studio Code from within the Cygwin window, rather than by clicking on its icon (otherwise, the language server will not be found):

diff --git a/src/ocamlorg_frontend/url.ml b/src/ocamlorg_frontend/url.ml index 8724fb5a96..1f89013d7e 100644 --- a/src/ocamlorg_frontend/url.ml +++ b/src/ocamlorg_frontend/url.ml @@ -72,3 +72,5 @@ let getting_started = tutorial "up-and-running-with-ocaml" let best_practices = "/learn/best-practices" let problems = "/problems" + +let platform s = "/platform/" ^ s diff --git a/src/ocamlorg_web/lib/redirection.ml b/src/ocamlorg_web/lib/redirection.ml index 5c620eb355..bc5b70fbcc 100644 --- a/src/ocamlorg_web/lib/redirection.ml +++ b/src/ocamlorg_web/lib/redirection.ml @@ -195,8 +195,7 @@ let from_v2 = ; "/consortium/index.fr.html", "/" ; "/contributors.fr.html", "/" ; "/platform/", "/" - ; "/platform/index.html", "/" - ; "/platform/ocaml_on_windows.html", "/" + ; "/platform/index.html", "/" (* ; "/platform/ocaml_on_windows.html", "/" *) ; "/governance.html", "/" ; "/docs/license.fr.html", "/" ; "/docs/license.html", "/" @@ -335,3 +334,9 @@ let manual = ; ( Url.manual_with_version "4.13.1" , "https://ocaml.org/releases/4.13/manual/index.html" ) ] + +(* TODO: Integrate a platform section to the site *) +let platform = + [ ( Url.platform "ocaml_on_windows.html" + , "https://ocaml.org/platform/ocaml_on_windows.html" ) + ] diff --git a/src/ocamlorg_web/lib/router.ml b/src/ocamlorg_web/lib/router.ml index f1d5ee23a3..97a4cc6559 100644 --- a/src/ocamlorg_web/lib/router.ml +++ b/src/ocamlorg_web/lib/router.ml @@ -114,6 +114,7 @@ let router t = ; package_route t ; graphql_route t ; redirection_routes Redirection.from_v2 + ; redirection_routes Redirection.platform ; redirection_routes Redirection.manual ; toplevels_route ; Dream.get "/media/**" (Dream.static ~loader:media_loader "") From d7f7bfce620016e4d5660a1ba2abe6a2376f9601 Mon Sep 17 00:00:00 2001 From: Patrick Ferris Date: Thu, 27 Jan 2022 09:54:32 +0000 Subject: [PATCH 3/3] Apply suggestions from code review Co-authored-by: Christine Rose --- data/tutorials/en/000_up_and_running.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/data/tutorials/en/000_up_and_running.md b/data/tutorials/en/000_up_and_running.md index d64c2901bd..a4f33d9f2f 100644 --- a/data/tutorials/en/000_up_and_running.md +++ b/data/tutorials/en/000_up_and_running.md @@ -67,9 +67,9 @@ sh <(curl -sL https://raw.githubusercontent.com/ocaml/opam/master/shell/install. ### For Windows OCaml on Windows is still a work in progress. In the meantime, if you only -need to *run* OCaml programs on a Windows machine, then the simplest solution is to use the Windows Subsystem for Linux 2 (WSL2). WSL2 is a feature that allows Linux programs to run directly on Windows. WSL2 is substantially easier and faster to use than WSL1. Microsoft have comprehensive installation steps for [setting up WSL2](https://docs.microsoft.com/en-us/windows/wsl/install-win10). +need to *run* OCaml programs on a Windows machine, then the simplest solution is to use the Windows Subsystem for Linux 2 (WSL2). WSL2 is a feature that allows Linux programs to run directly on Windows. WSL2 is substantially easier and faster to use than WSL1. Microsoft has comprehensive installation steps for [setting up WSL2](https://docs.microsoft.com/en-us/windows/wsl/install-win10). -On the other hand, if you need Windows binaries then you will have to use the [OCaml for Windows](https://fdopen.github.io/opam-repository-mingw/) installer which comes in 32bit and 64bit versions. This installer gives you opam and OCaml installations all in one go. It is used from within a Cygwin environment, but the executables produced have no dependency on Cygwin at all. For a more comprehensive update on the state of OCaml on Windows, see the [OCaml on Windows](/platform/ocaml_on_windows.html) page on the old version of the site. +On the other hand, if you need Windows binaries, you will have to use the [OCaml for Windows](https://fdopen.github.io/opam-repository-mingw/) installer which comes in 32bit and 64bit versions. This installer gives you Opam and OCaml installations all in one go. It's used from within a Cygwin environment, but the executables produced have no dependency on Cygwin at all. For a more comprehensive update on the state of OCaml on Windows, see the [OCaml on Windows](/platform/ocaml_on_windows.html) page on the old version of the site. ## The OCaml top level @@ -204,7 +204,7 @@ from the list. Now, help is available by hovering over symbols in your program: ![Visual Studio Code](/media/tutorials/vscode.png "") -**On Windows using WSL2** you will remotely connect to your WSL2 instance from Visual Studio Code. Microsoft have a [useful blog post](https://code.visualstudio.com/blogs/2019/09/03/wsl2) covering getting WSL2 and Visual Studio Code connected. +**On Windows using WSL2**, you will remotely connect to your WSL2 instance from Visual Studio Code. Microsoft has a [useful blog post](https://code.visualstudio.com/blogs/2019/09/03/wsl2) covering getting WSL2 and Visual Studio Code connected. **On Windows**, we must launch Visual Studio Code from within the Cygwin window, rather than by clicking on its icon (otherwise, the language server will not be