haskell / haskell/cabal

Document the relationship between ComponentId, UnitId, MungedPackageId, PackageId etc.

Open
#5,809 15 comments 1 reaction 2 assignees Claimed by @hvr View on GitHub
documentation
Dominant language
Haskell
Stars
1.7k
Forks
750
Avg merge
4d 3h
Merged PRs (30d)
28

Description

There are these types: `ComponentId`, `UnitId`, `MungedPackageId`, `PackageId` etc. which all seems to be *same same but different*. There should be a **technical note** in the code describing their relationship, with
- links issues describing planned clean ups to be done (and what's blocking them, if they cannot be done)
- whether the types are intended to be used in public text-based APIs
- with remarks what's the current state, previous point
- haddocks of these types pointing to the note.

---

Honestly, I have no idea what are the subtle differences about these types, and I won't read through GitHub issues to find out. The note in the code would be the right place to refer.

---

As an example, `ComponentId` is documented as

> For non-Backpack components, this corresponds one to one with
> the 'UnitId', which serves as the basis for install paths,
> linker symbols, etc.

And there are no remarks how things are different in Backpack case.

---

Related issue https://github.com/haskell/cabal/issues/4761

There is a *Mapping from semantic objects in this thesis (Fig. 3.5 and Fig. 6.1) to their definitions
in GHC* table in Edwards thesis. Something similar but for Cabal types would be great to have too.

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.