Skip to content
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.

Sign up for GitHub

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

Jump to bottom

Add minimal example to README #533

Open
wants to merge 2 commits into
base: main
Choose a base branch
from
Open

Add minimal example to README #533

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
e4e5786
Add minimal example to README
roosemberth Nov 26, 2022
8391b73
Merge branch 'main' into add-minimal-example-in-readme
mpilgrem Jun 16, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
29 changes: 29 additions & 0 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -32,6 +32,35 @@ at the Singapore Haskell meetup: http://typeful.net/talks/hpack

## Examples

Copy link
Collaborator

Choose a reason for hiding this comment

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

It may be worth acknowledging in the introduction that users of Stack have access to templates for projects that include package.yaml files, but users of Cabal (the tool) may find the minimal example useful.

The following `package.yaml` describes a project with a library under `src`, an executable under `app/Main.hs` and tests under `test/Main.hs`:
Copy link
Collaborator

Choose a reason for hiding this comment

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

I think, strictly, (if you follow my other suggestions below):

... a package with a main library with source code under directory `src`, an
executable named `my-exe` with source code under `app`, and a test suite named
`my-test-suite` with source code under `test`:


```yaml
Copy link
Collaborator

Choose a reason for hiding this comment

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

I would include spec-version: 0.36.0, to ensure modern behaviour.

name: mylib
Copy link
Collaborator

Choose a reason for hiding this comment

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

Perhaps my-package would be a better dummy name, as this will produce a Cabal file for a package with more than a library component.


dependencies:
- base >= 4.9 && < 5
Copy link
Collaborator

Choose a reason for hiding this comment

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

What is the basis for these bounds? The generated Cabal file will specify cabal-version: 1.12 which might imply base >= 4.4 (GHC 7.2.1 came with Cabal-1.12.0).


library:
source-dirs: src

executable:
Copy link
Collaborator

Choose a reason for hiding this comment

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

While executable: { ... } is strictly minimal, perhaps executables: { my-exe: { ... } } would be more useful?

main: Main.hs
source-dirs: app
dependencies:
- mylib

tests:
spec:
Copy link
Collaborator

Choose a reason for hiding this comment

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

Perhaps my-test-suite or my-package-test (given what cabal init would suggest) would be a better dummy name than spec?

main: Main.hs
source-dirs:
- test
- src
Copy link
Collaborator

Choose a reason for hiding this comment

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

For a minimal example, why include src as a source directory for the source code of a test suite application (also given what cabal init would suggest)?

dependencies:
- QuickCheck
Copy link
Collaborator

Choose a reason for hiding this comment

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

For a minimal example, I would expect a dependency on the package itself but not QuickCheck.

```

### More examples

* Given this [package.yaml](https://github.com/sol/hpack/blob/master/package.yaml) running `hpack` will generate [hpack.cabal](https://github.com/sol/hpack/blob/master/hpack.cabal)
* Given this [package.yaml](https://github.com/zalora/getopt-generics/blob/master/package.yaml) running `hpack` will generate [getopt-generics.cabal](https://github.com/zalora/getopt-generics/blob/master/getopt-generics.cabal)
* Given this [package.yaml](https://github.com/hspec/sensei/blob/master/package.yaml) running `hpack` will generate [sensei.cabal](https://github.com/hspec/sensei/blob/master/sensei.cabal)
Expand Down
Loading