Skip to content

Port contents of Documentation/ModuleAliasing.md to DocC #8730

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
wants to merge 1 commit into
base: main
Choose a base branch
from

Conversation

bripeticca
Copy link
Contributor

Fixes #8588

Migrate the contents of Documentation/ModuleAliasing.md to our DocC catalog in Sources/PackageManagerDocs/Documentation.docc/ModuleAliasing.md.

@@ -0,0 +1,205 @@
# Module Aliasing

Learn how to use module aliasing with SwiftPM.
Copy link
Member

Choose a reason for hiding this comment

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

Suggested change
Learn how to use module aliasing with SwiftPM.
Create aliased names for modules to avoid collisions between targets in your package or its dependencies.

^ What do you think of the above as an abstract - calling out the action you'd take (what this article describes), and why you'd want/need to do so.


## Overview

The number of package dependencies often grows, with that, a name collision can occur among modules from different packages. Module names such as `Logging` or `Utils` are common examples. In order to resolve the collision, SwiftPM (in 5.7+) introduces a new parameter `moduleAliases`, which allows a user to define new unique names for the conflicting modules without requiring any source code changes.
Copy link
Member

Choose a reason for hiding this comment

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

Suggested change
The number of package dependencies often grows, with that, a name collision can occur among modules from different packages. Module names such as `Logging` or `Utils` are common examples. In order to resolve the collision, SwiftPM (in 5.7+) introduces a new parameter `moduleAliases`, which allows a user to define new unique names for the conflicting modules without requiring any source code changes.
As you add dependencies to your package, a name collision can occur among modules from different packages.
Module names such as `Logging` or `Utils` are common examples.
In order to resolve the collision, package manager, from Swift 5.7 or later, provides the parameter `moduleAliases` when defining dependencies for targets.
You define new unique names for the modules that would otherwise conflict, without requiring any source code changes.

Breaking up the sentences to one per line, and revising some of them towards active voice, as well as spelling out the detail about Swift 5.7 or later being required.

The `Utils` module from package `a-utils` will be renamed as `DrawUtils`, and `Utils` from package `c-utils` will be renamed as `GameUtils`. Each overridden alias will be applied to all of the targets that depend on each module.


### Requirements
Copy link
Member

Choose a reason for hiding this comment

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

I'm still thinking your idea of moving this up to the top of the article would be much better - and the first line item can be dropped, as it's clearly spelled out in the overview, which introduces the idea of a module alias.

As I'm reading this through later, this list of constraints on using module aliasing seems like it would be great as a second paragraph in the overview, just to get it up front and clearly in eyes view when hitting this page.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Development

Successfully merging this pull request may close these issues.

Migrate documentation for Module Aliasing to DocC
2 participants