On this page:
6.1 Are package installations versioned with respect to the Racket version?
6.2 Where and how are packages installed?
6.3 How are user-specific and installation-wide package scopes related for conflict checking?
6.4 Do I need to change a package’s version when I update a package with error fixes, etc.?
6.5 How can I specify which version of a package I depend on if its interface has changed and I need an old version?
6.6 Why is the package manager so different than PLane T?

6 FAQ

This section answers anticipated frequently asked questions about the package manager.

6.1 Are package installations versioned with respect to the Racket version?

By default, when you install a package, it is installed for a specific user and a specific version of Racket. That is, the package scope is user- and version-specific.

You can change the default package scope (for a particular Racket installation) with raco pkg config -i --set default-scope installation, in which case package operations apply for all users of a Racket installation. You can also use the -i or --installation flag with a specific raco pkg command, instead of changing the default scope for all uses of raco pkg. Note that an installation-wide package is not exactly version-specific, because the version of an installation can change if it corresponds to a source-code checkout that is periodically updated and rebuilt.

If you change the default package scope, you can use the -u or --user flag with a specific raco pkg command to perform the command with user- and version-specific package scope.

Finally, you can use the -s or --shared flag with raco pkg commands to install user-specific packages that apply to all Racket versions that you run. (In contrast, PLaneT requires reinstallation of all packages every version change.)

6.2 Where and how are packages installed?

User-specific and Racket-version-specific packages are in (build-path (find-system-path 'addon-dir) (version) "pkgs"), user-specific and all-version packages are in (build-path (find-system-path 'addon-dir) "pkgs"), and installation-wide packages are in (build-path (find-lib-dir) "pkgs"). They are linked as collection roots with raco link.

6.3 How are user-specific and installation-wide package scopes related for conflict checking?

User-specific packages are checked against installation-wide packages for conflicts. Installation-wide packages are checked only against other installation-wide packages.

Beware that a new installation-wide package can invalidate previous conflict checks for user-specific packages. Similarly, new user-specific but all-version packages can invalidate previous user-specific conflict checks for a different Racket version.

6.4 Do I need to change a package’s version when I update a package with error fixes, etc.?

If you have new code for a package, then it should have a new checksum. When package updates are searched for, the checksum of the installed package is compared with the checksum of the source, if they are different, then the source is re-installed. This allows code changes to be distributed. You do not need to declare an update a version number, except to allow other package implementors to indicate a dependency on particular features (where a bug fix might be considered a feature, but it is not usually necessary to consider it that way).

6.5 How can I specify which version of a package I depend on if its interface has changed and I need an old version?

In such a situation, the author of the package has released a backwards incompatible edition of a package. The package manager provides no help to deal with this situation (other than, of course, not installing the “update”). Therefore, package authors should not make backwards incompatible changes to packages. Instead, they should release a new package with a new name. For example, package libgtk might become libgtk2. These packages should be designed to not conflict with each other, as well.

6.6 Why is the package manager so different than PLaneT?

There are two fundamental differences between PLaneT and this package manager.

The first is that PLaneT uses “internal linking” whereas the current package manager uses “external linking.” For example, an individual module requires a PLaneT package directly in a require statement:

(require (planet game/tic-tac-toe/data/matrix))

whereas using the package manager, the module would simply require the module of interest:

(require data/matrix)

and would rely on the external system having the tic-tac-toe package installed.

This change is good because it makes the origin of modules more flexible—so that code can migrate in and out of the core, packages can easily be split up, combined, or taken over by other authors, etc.

This change is bad because it makes the meaning of your program dependent on the state of the system.

The second major difference is that PLaneT is committed to guaranteeing that packages that never conflict with one another, so that any number of major and minor versions of the same package can be installed and used simultaneously. The package manager does not share this commitment, so package authors and users must be mindful of potential conflicts and plan around them.

This change is good because it is simpler and lowers the burden of maintenance (provided most packages don’t conflict.)

The change is bad because users must plan around potential conflicts.

In general, the goal of the package manager is to be a lower-level system, more like the package systems used by operating systems. The goals of PLaneT are not bad, but we believe they are needed infrequently and a system like PLaneT could be more easily built atop the package manager than the reverse.

In particular, our plans to mitigate the downsides of these changes are documented in Short Term.