Skip to content

Commit

Permalink
Docs: clarify yarn v1 vs yarn v3+ installation #3871
Browse files Browse the repository at this point in the history
  • Loading branch information
@lovell
lovell committed Dec 4, 2023
1 parent 4d049ee commit 004fff9
Showing 1 changed file with 8 additions and 1 deletion.
9 changes: 8 additions & 1 deletion docs/install.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -13,7 +13,14 @@ pnpm add sharp
```

```sh
yarn add sharp # v3 recommended, Plug'n'Play unsupported
# yarn v3+ (Plug'n'Play is unsupported)
yarn config set nodeLinker node-modules
yarn add sharp
```

```sh
# yarn v1 (maintenance mode)
yarn add sharp --ignore-engines
```

```sh
Expand Down

7 comments on commit 004fff9

@jdpt0
Copy link

@jdpt0 jdpt0 commented on 004fff9 Dec 4, 2023

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Would unplugging be enough for Yarn PnP? https://yarnpkg.com/cli/unplug

@lovell
Copy link
Owner Author

@lovell lovell commented on 004fff9 Dec 4, 2023

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I was hopeful for this originally but based on my testing no, I don't think so.

We need to know relative paths between packages at compile time, prior to running npm publish, to ensure rpath values embedded in binaries are correct.

However yarn "unplugs" npm tarballs into directories where the path contains a content-based hash of the npm-published tarball. You can probably see the catch 22 situation here; a tarball cannot contain its own hash.

@arcanis
Copy link

@arcanis arcanis commented on 004fff9 Dec 9, 2023

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Do you have details? Why do you need to hardcode a relative path? Can't require.resolve be used to get the path to the package you're looking for?

@lovell
Copy link
Owner Author

@lovell lovell commented on 004fff9 Dec 10, 2023

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

At compile time, sharp binaries (essentially shared library files) are built with a series of relative paths to the libvips shared libraries.

Here are the values for Linux (macOS is similar, Windows uses a totally different approach):

sharp/src/binding.gyp

Lines 176 to 179 in 004fff9

'-Wl,-rpath=\'$$ORIGIN/../../sharp-libvips-<(platform_and_arch)/lib\'',
'-Wl,-rpath=\'$$ORIGIN/../../../sharp-libvips-<(platform_and_arch)/<(sharp_libvips_version)/lib\'',
'-Wl,-rpath=\'$$ORIGIN/../../node_modules/@img/sharp-libvips-<(platform_and_arch)/lib\'',
'-Wl,-rpath=\'$$ORIGIN/../../../node_modules/@img/sharp-libvips-<(platform_and_arch)/lib\''

We need to know all the possible locations that the @img/sharp-libvips-<platform> packages will be on the filesystem relative to the @img/sharp-<platform> packages.

This allows libvips binaries to be published independently of sharp binaries, which for example allows (for Linux and macOS) new releases of sharp without also downloading all of libvips and its dependencies every time.

My understanding of yarn Plug'n'Play is that it unpacks npm-published tarballs into directories with names that contain a hash e.g. @img-sharp-darwin-x64-npm-0.33.0-91623871fa. yarn exposes this at runtime via require.resolve but we need to know the 91623871fa section of this directory name at build time, before anything is published to npm.

@arcanis
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I may be wrong, but I think you may be able to avoid the hardcode by using a gyp variable; similar to what you do here, you should be able to do:

'sharp_libvips_lib': '<!(node -p "path.dirname(require.resolve(\'@img/sharp-libvips-<(platform_and_arch)/package.json\'))"',

@lovell
Copy link
Owner Author

@lovell lovell commented on 004fff9 Dec 10, 2023

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks Maël, I've created #3888 to track this.

@lovell
Copy link
Owner Author

@lovell lovell commented on 004fff9 Dec 17, 2023

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

sharp v0.33.1 now provides support for yarn Plug'n'Play.

Please sign in to comment.