Symlinks don't work reliably on Windows

[jonahbeckford]

There are several symlinks in the docs/ folder; maybe elsewhere as well. Three problems:

1. Many Windows machines do not support symlinks.
2. Even if they do, often you need administrator permission to enable them.
3. Even when symlinks are enabled, you can't create dangling symlinks. So in docs/graph-b_avar.html -> graph-dot-b_avar.html if the symlink docs/graph-b_avar.html is created before graph-dot-b_avar.html, there is a dangling symlink that will be rejected.

Can the 6-year old symlinks be removed?

---

Error:

#=== ERROR while fetching sources for bogue.20231209 ==========================#
OpamSolution.Fetch_fail("\027[33m#\027[0m \027[33mpath\027[0m        Y:\\source\\DkHelloScript\\docs\n\027[33m#\027[0m \027[33mcommand\027[0m     C:\\Users\\beckf\\AppData\\Local\\Programs\\DKMLNA~1\\tools\\MSYS2\\usr\\bin\\tar.exe xfz /y/user/beckf/packages/opam/download-cache/md5/70/7001dfb28e03db2169212b607c33917c -C /c/Users/beckf/AppData/Local/Temp/opam-61824-8667f5\n\027[33m#\027[0m \027[33mexit-code\027[0m   2\n\027[33m#\027[0m \027[33menv-file\027[0m    Y:\\user\\beckf\\packages\\opam\\log\\log-61824-e1ca8f.env\n\027[33m#\027[0m \027[33moutput-file\027[0m Y:\\user\\beckf\\packages\\opam\\log\\log-61824-e1ca8f.out\n\027[33m### output ###\n\027[0m\027[33m# \027[0m[...]\n\027[33m# \027[0m/c/Users/beckf/AppData/Local/Programs/DKMLNA~1/tools/MSYS2/usr/bin/tar: bogue-20231209/docs/graph-b_time.html: Cannot create symlink to \226\128\152graph-dot-b_time.html\226\128\153: No such file or directory\n\027[33m# \027[0m/c/Users/beckf/AppData/Local/Programs/DKMLNA~1/tools/MSYS2/usr/bin/tar: bogue-20231209/docs/graph-b_timeout.html: Cannot create symlink to \226\128\152graph-dot-b_timeout.html\226\128\153: No such file or directory\n\027[33m# \027[0m/c/Users/beckf/AppData/Local/Programs/DKMLNA~1/tools/MSYS2/usr/bin/tar: bogue-20231209/docs/graph-b_trigger.html: Cannot create symlink to \226\128\152graph-dot-b_trigger.html\226\128\153: No such file or directory\n\027[33m# \027[0m/c/Users/beckf/AppData/Local/Programs/DKMLNA~1/tools/MSYS2/usr/bin/tar: bogue-20231209/docs/graph-b_tvar.html: Cannot create symlink to \226\128\152graph-dot-b_tvar.html\226\128\153: No such file or directory\n\027[33m# \027[0m/c/Users/beckf/AppData/Local/Programs/DKMLNA~1/tools/MSYS2/usr/bin/tar: bogue-20231209/docs/graph-b_update.html: Cannot create symlink to \226\128\152graph-dot-b_update.html\226\128\153: No such file or directory\n\027[33m# \027[0m/c/Users/beckf/AppData/Local/Programs/DKMLNA~1/tools/MSYS2/usr/bin/tar: bogue-20231209/docs/graph-b_utf8.html: Cannot create symlink to \226\128\152graph-dot-b_utf8.html\226\128\153: No such file or directory\n\027[33m# \027[0m/c/Users/beckf/AppData/Local/Programs/DKMLNA~1/tools/MSYS2/usr/bin/tar: bogue-20231209/docs/graph-b_utils.html: Cannot create symlink to \226\128\152graph-dot-b_utils.html\226\128\153: No such file or directory\n\027[33m# \027[0m/c/Users/beckf/AppData/Local/Programs/DKMLNA~1/tools/MSYS2/usr/bin/tar: bogue-20231209/docs/graph-b_var.html: Cannot create symlink to \226\128\152graph-dot-b_var.html\226\128\153: No such file or directory\n\027[33m# \027[0m/c/Users/beckf/AppData/Local/Programs/DKMLNA~1/tools/MSYS2/usr/bin/tar: bogue-20231209/docs/graph-b_widget.html: Cannot create symlink to \226\128\152graph-dot-b_widget.html\226\128\153: No such file or directory\n\027[33m# \027[0m/c/Users/beckf/AppData/Local/Programs/DKMLNA~1/tools/MSYS2/usr/bin/tar: bogue-20231209/docs/graph-b_window.html: Cannot create symlink to \226\128\152graph-dot-b_window.html\226\128\153: No such file or directory\n\027[33m# \027[0m/c/Users/beckf/AppData/Local/Programs/DKMLNA~1/tools/MSYS2/usr/bin/tar: bogue-20231209/docs/graph-bogue.html: Cannot create symlink to \226\128\152graph-dot-bogue.html\226\128\153: No such file or directory\n\027[33m# \027[0m/c/Users/beckf/AppData/Local/Programs/DKMLNA~1/tools/MSYS2/usr/bin/tar: Exiting with failure status due to previous errors\n")

---

Mitigation 1: opam pin https://github.com/sanette/bogue.git#20231209 does work on my machine, but that is only because recent Git versions try to work-around the problem 3, and because 1 + 2 do not apply to my machine. But it does suggest that if you really need those symlinks in your git source tree, then removing the symlinks from https://github.com/sanette/bogue/archive/20231209.tar.gz (new version needed!) is a reasonable workaround.

[sanette]

Hi, these symlinks look old indeed, but their targets are updated regularly.

That being said, while they are convenient, they are not strictly necessary: I can modify the html files so that the refer directly to the real targets. I will do this! Thanks for the report

[sanette]

done in : https://github.com/sanette/bogue/commit/5c2e8dbee93ec13ffacf1bd55aaabe407cb17dc5

[jonahbeckford]

Thanks! I tested with:

opam pin bogue.20240214 https://github.com/sanette/bogue/archive/5c2e8dbee93ec13ffacf1bd55aaabe407cb17dc5.tar.gz

and that source problem disappeared.

(I've got other regression issues with SDL2 unrelated to Bogue.)

[jonahbeckford]

Thanks.