Unable to bundle on Windows 10 because of a symlink.

[KOlofinmoyin]

Pre-conditions (platform setup):

1. OS: Windows 10 Pro
2. IDE: Atom 2020 06 29 12
3. Rails version: Rails 6.0.3.2
4. Ruby version: ruby 2.6.6p146 (2020-03-31 revision 67876) [x64-mingw32]
5. Administrate version: administrate 0.13.0

Steps to repro:

1. Create a rails app. (having one or more models), open the app., then
2. Open its Gem file
3. Insert the line: gem ‘Administrate’ to the last line of the file
4. Open terminal and run: bundle install

Expected behaviour:

1. Administrate Gem is successfully bundled.

Actual behaviour:

1. User is presented with the error-message:

Installing administrate 0.13.0
_Errno::EACCES: Permission denied @ rb_file_s_symlink - (../CONTRIBUT
TING.md,
C:/Ruby26-x64/lib/ruby/gems/2.6.0/gems/administrate-0.13.0/docs/cont
tributing.md)
An error occurred while installing administrate (0.13.0), and Bundle
er cannot
continue.
Make sure that gem install administrate -v '0.13.0' --source 'https://rubygems.org/' succeeds before bundling.

In Gemfile:
administrate_
(see youtube link: https://youtu.be/n-80J7F1spk )

[nickcharlton]

In #1514, we added a symlink so that the docs would show up on the demo app (which, ironically, you can't see as I never deployed that version) …but symlinks aren't supported on Windows so hence we're getting this error.

There's two potential solutions I can think of here:

1. We drop the whole docs/ folder from the distributed gem which might cause another problem,
2. We allow overriding the list of docs the DocsController knows to pick up. This would also potentially solve the weird YAML frontmatter problem we gave up with in Provide <title> tags for doc pages #1537, where you see a bunch of metadata at the top of the README.

To do that, we'd still need to solve the intention of #1537 by providing some sort of file metadata so I suspect having some sort of lookup table would be the safest way to do this, something like this perhaps:

SPECIAL_FILES = [
  {
    page: "../README",
    title: "README",
  } 
]

which would mean it'd still work with the implementation we have here:

administrate/spec/example_app/app/controllers/docs_controller.rb

Lines 34 to 36 in 844c270

	def full_page_path(page)
	Rails.root + "../../#{page}.md"
	end

Anyway, there might be a better solution to this, I'm just thinking aloud. How do you feel about taking a look at that?

[KOlofinmoyin]

Sure, will do Nick. Thanks for the demo.

[nickcharlton]

We've mostly solved this problem for Administrate now in #1698, which handily starts to solve some documentation problems which weren't ideal otherwise, too.

Trying to bundle with that solution means Administrate itself is okay, but some other dependencies aren't. That's potentially worth solving in those projects, but from looking into how to how to do development on Windows in 2020 …not actually using Windows seems the best option through Windows Subsystem for Linux. I did go to look into this and so here's some notes for the future on doing that:

1. Using Scott Hanselman's article as a broad guide,
2. But installing the WSL 2 version using the Microsoft guide,
3. And some of the Ruby / Postgres suggestions in Chris' article,
4. I also needed Node, which I did from a Node Source package for 14,
5. And PhantomJS, using this Gist which seems to work alright (but with 2.1, rather than the version it listed)

I can now run bin/rspec and the whole suite passes.

[djberg96]

In #1514, we added a symlink so that the docs would show up on the demo app (which, ironically, you can't see as I never deployed that version) …but symlinks aren't supported on Windows so hence we're getting this error.

Totally random comment outta nowhere (don't ask me how I ended up here), but actually Windows has supported symlinks since Windows Vista. It's just that you need either administrator privileges, or a user with SeCreateSymbolicLinkPrivilege rights.

You can check your current privileges with whoami /priv

[pablobm]

@djberg96 - Uh, I had no idea. It's still best not to use symlinks in packages like this one, but that info may still be helpful in the future. Thank you!

(How did you end up here? 😝)