Symbolic links files in project

help
1

This question may off-topic, I found a lot of project has some sort of "Symbolic Links" files, usually for Licenses or README.md, the file just with a relative path in it, for example:

../README.md

And I have even seen some project use this to "link" source code outside the crate (usually from another crate of the same workspace).

I wondered is this a feature of cargo or some other tools, is there any documentation for this?

P.S. For example, this or this, serde use this to include source codes

P.P.P.S: If I publish a crate to crate.io, what happens to a symlinks? Does the cargo copy the real file(since there's no workspace in crate.io, just crates.)?,

2

Example?

3

For example, this or this, serde use this to include source codes

4

If you clone it your local machine, then you aren't going to get a file with those contents, but instead you will get a real symlink. The ../README.md string is just how GitHub displays a symlink.

5

Seems not true(on Windows)... I cloned the crate serde, it is a file indeed, the same as what it looks like in github...

6

Well, I don't think Windows has symlinks. I cloned the serde repository you linked on my Linux machine, and it gave me real symlinks.

7

I tried on a Mac, and yes it turns to a real symbol, So it is just a UNIX-Like symbolic links, no magics here? But if it is a normal symbol link, it shouldn't be readable (not even as strings) on Windows...

8

I believe that this is just how git handles symlinks on windows.

9

Windows does have symlinks. Only they are more limited than on POSIX platforms.

In particular they require SeCreateSymbolicLink permission, which, practically, implies Admin.

That's why by default git copies files instead of trying to use symlinks. But that option is available.

There are long discussion about that on StackOverflow.

I think it's better to continue discussion there because it's not Rust-specific at all.

10

I ask here because I got further questions, if I publish a crate to crate.io, what happens to a symlinks? Does the cargo copy the real file(since there's no workspace in crate.io, just crates.)? I checked some imported crates, it seems that it does copy the real files, but I'm not sure how it is done (not sure if it is done automatically, or manually be someone who upload his crate).

11

If you want to publish from Windows then IMO it's better to fight Windows a bit (enable Developer's Mode, reinstall Git with symlinks support, change git repos to ensure core.symlinks is set to true in your crate) rather than hope that cargo would scan your project and turn file copies back into symlinks.

3 Likes
12

You just need to enable "Developer Mode" (search in settings). And git may require setting:

git config --global core.symlinks=true

From then on any repos you clone will use symlinks.

2 Likes
13

This topic was automatically closed 90 days after the last reply. We invite you to open a new topic if you have further questions or comments.