Ch-01 What do we mean when we say cabal? #26

srirajshukla · 2021-07-21T19:29:31Z

This chapter contains the different meanings of the term cabal.

Right now, I've just added the basic skeleton. I'll be adding more information about the topic.

Some starter information about the different meanings for the cabal.

srirajshukla · 2021-07-21T19:31:02Z

@JonathanLorimer Sorry for being so late on this! I got caught up with some other work. I've started working on it and took some inspiration from your article.

Is the structure that I'm following right now okay or should I make some changes?

JonathanLorimer · 2021-07-21T19:34:07Z

@srirajshukla Hey, thanks for taking this up, and no worries life happens. The structure looks fine for now, I will probably have more to say as you write the sections out.

srirajshukla · 2021-08-03T20:23:32Z

Hi @JonathanLorimer, when I am trying to make a commit, I'm getting the error that custom prettier failed even though I've formatted the file with prettier and manually checked with it as well.

bash-4.4$ prettier -c "src/preamble/01_what_do_we_mean_when_we_say_cabal.md"
Checking formatting...
All matched files use Prettier code style!
bash-4.4$ git commit -m "Added details about cabal-install, CABAL, .cabal"
[WARNING] Unstaged files detected.
[INFO] Stashing unstaged files to /home/sok/.cache/pre-commit/patch1628022078.
Custom Prettier..........................................................Failed
- hook id: custom-prettier
- files were modified by this hook

src/preamble/01_what_do_we_mean_when_we_say_cabal.md

nixpkgs-fmt..........................................(no files to check)Skipped
[WARNING] Stashed changes conflicted with hook auto-fixes... Rolling back fixes...
[INFO] Restored changes from /home/sok/.cache/pre-commit/patch1628022078.

Mikolaj · 2021-08-03T20:30:46Z

Perhaps do git add various_files before git commit or do git commit -a -m "foo"?

srirajshukla · 2021-08-03T20:36:55Z

I got it working, the pre-commit hook was suggesting a change. I wasn't staging it. 😅

JonathanLorimer · 2021-08-06T16:17:36Z

@srirajshukla Glad you got it figured out. Sorry for the friction, it can sometimes be a contentious issue whether pre-commit hooks should automatically stage changes or not. Also sorry for the radio silence, I was on vacation. I will have a look at this PR today!

JonathanLorimer · 2021-08-06T17:19:43Z

Just posting some screenshots of running the build locally to demonstrate that things look as though they are styled correctly!

srirajshukla · 2021-08-06T18:09:17Z

@JonathanLorimer Hope you had a great vacation! Yeah, about the pre-commit hook thing, can we add it somewhere (maybe in contributing.md or someplace like that).

I think I am missing a few references and links, so I'll add them too. And maybe a bit more in the cabal library section.

JonathanLorimer

This is a great start. Thanks again for your contribution. I know I left a lot of comments but I think this is a really great first attempt. Please ping me if you have any questions!

src/preamble/01_what_do_we_mean_when_we_say_cabal.md

JonathanLorimer · 2021-08-06T17:28:20Z

src/preamble/01_what_do_we_mean_when_we_say_cabal.md

+1. [cabal-install](#cabalInstall) is the command line utility to help configure,
+   compile and install Haskell libraries and programs.
+
+2. [The Cabal build system](#cabailBuildSystem), a specification for defining


Typo here.

Suggested change

2. [The Cabal build system](#cabailBuildSystem), a specification for defining

2. [The Cabal build system](#cabalBuildSystem), a specification for defining

Is the cabal build system a specification? I think you should also be clear that you are talking about what it commonly referred to as Cabal (upper case c) here. I think you are 100% right that it is a library that is used by other haskell packages. It might be worth mentioning that Cabal can take a haskell dependency graph (of external and internal modules) and use GHC to build it.

I'll change Cabal build to CABAL build. I can mention "Cabal can take a haskell dependency graph (of external and internal modules) and use GHC to build it." in the details section?

@JonathanLorimer what would be better? adding it here in tldr section or in the more details section?

@srirajshukla I am okay with you mentioning the dependency graph bit in the details section. But I still think you need to be careful about using the word specification. It could be confused with the .cabal file being a specification for your haskell package. Also I don't think Cabal is really a specification, it is really just a library and a build system.

src/preamble/01_what_do_we_mean_when_we_say_cabal.md

JonathanLorimer · 2021-08-06T17:33:45Z

src/preamble/01_what_do_we_mean_when_we_say_cabal.md

+2. [The Cabal build system](#cabailBuildSystem), a specification for defining
+   Haskell packages, together with a library for performing builds. This build
+   system is used by cabal-install and other package managers (stack for eg).
+   For eg: parsing .cabal files (among others).


Can you expand on this?

I was thinking I'd just add one or two-line summaries here. I'll add some more details here then!

@srirajshukla I am fine with this tl;dr section being small. But I think if you introduce a concept (like parsing a .cabal file) you need to fully flesh it out, otherwise just don't mention it.

src/preamble/01_what_do_we_mean_when_we_say_cabal.md

JonathanLorimer · 2021-08-06T18:19:05Z

src/preamble/01_what_do_we_mean_when_we_say_cabal.md

+projects whose sets of dependencies might conflict with each other within the
+confines of a single system. When cabal-install is asked to build a project, by


Perhaps you could mention something about version ranges here? https://cabal.readthedocs.io/en/latest/developing-packages.html#modules-imported-from-other-packages

You don't need to go into very much detail, but it might be helpful for the user to understand that they specify a range of acceptable versions and cabal sets out to solve a working package set within those ranges.

I'll add a bit about it here.

@JonathanLorimer I've added this much:
"Packages provide a constraint on the version of
various libraries (version range) that will work with their package."

Is this enough?

Yeah that is fine, maybe add something like "Packages provide a constraint on the version of
various libraries (using cabal's version bounds syntax) that will work with their package."

src/preamble/01_what_do_we_mean_when_we_say_cabal.md

1. Rewrote about `.cabal` section 2. Changed tl;dr for cabal library and added a bit more about it. 3. Changed inline href from anchor tags to direct linking. 4. Fixed typos.

srirajshukla · 2021-08-09T19:41:36Z

@JonathanLorimer

JonathanLorimer · 2021-08-09T19:47:42Z

@srirajshukla Thanks for getting these changes in so quickly! I will give this a review tonight.

src/preamble/01_what_do_we_mean_when_we_say_cabal.md

JonathanLorimer · 2021-08-10T00:01:12Z

src/preamble/01_what_do_we_mean_when_we_say_cabal.md

+out a set of packages and package versions that satisfy it. This set of packages
+is drawn from all package and all versions from Hackage as a whole. The chosen
+versions of the dependenices will be installed and indexed in a database in the
+cabal directory.


do you mean ~/.cabal directory? I am pretty sure that's the correct one. It would be good to confirm this in the cabal docs either way.

srirajshukla · 2021-08-16T18:35:59Z

@JonathanLorimer I was sick for a few days so I didn't do it earlier. I've made the changes.

srirajshukla · 2021-09-02T17:34:28Z

Hi @JonathanLorimer , please review it when you've got some time

JonathanLorimer

If you include a couple of the suggestions I left, I am happy to approve this. Thanks for the contribution!

src/preamble/01_what_do_we_mean_when_we_say_cabal.md

1. Fixed some typos pointed out in code review. 2. Added more information on Haskell implementations.

srirajshukla · 2021-09-08T19:20:16Z

@JonathanLorimer I hope it is fine now. 😅

JonathanLorimer · 2021-09-09T13:29:06Z

@Mikolaj can you give this a review?

Mikolaj · 2021-09-09T14:24:07Z

@Mikolaj can you give this a review?

Not right now, but yes, with pleasure.

jhrcek

Nice work 👍

jhrcek · 2021-09-10T04:02:12Z

src/preamble/01_what_do_we_mean_when_we_say_cabal.md

+The package properties describe the package as a whole, such as name, license,
+author, dependenices, etc. It also contains optional information about optional
+components such as
+[library properties](../new_to_cabal/06_first_cabal_library.md),


Nitpick:
"about optional components such as library properties" - sounds weird. Is "library property" an optional component?
I'd change this to [libraries]. Also in the "optional information about optional components" I'd drop the first "optional".
Since the component is optional, it means it can be left out, so no need to mention the optionality twice.

Yep, agree. I'll remove the first optional.

1. Fixed some typos pointed out in code review. 2. Added more information on Haskell implementations.

…erguide into chapter-01

Mikolaj · 2021-09-18T21:08:05Z

I apologise for the delay in reviewing --- we've just had regressions discovered in the published 3.6 and also CI got completely broken by changes in GitHub Actions. We are still saving the world, but I will review later, unless somebody else does and unblocks you.

Mikolaj · 2021-09-27T14:43:39Z

OK, I'm back, will review RSN. :)

Mikolaj

I like the choice of material, technical accuracy and style. Good job!

Mikolaj · 2021-09-27T19:02:48Z

src/preamble/01_what_do_we_mean_when_we_say_cabal.md

@@ -1 +1,96 @@
 # What do we mean when we say cabal?
+
+Cabal is an umbrella term that can refer to either "cabal the spec" (.cabal


"the package spec"? I wasn't sure if you mean "specification of the cabal software system" or "cabal format spec" or "cabal protocol spec".

Mikolaj · 2021-09-27T19:41:22Z

src/preamble/01_what_do_we_mean_when_we_say_cabal.md

+## tl;dr
+
+1. [.cabal file](#the-cabal-file) This is the file that specifies the content of
+   Haskell packages. The types of information that can be provided via the


I'd cross out "that can be". There is not so much optionality here, no defaults, a lot of the info is mandatory.

Mikolaj · 2021-09-27T19:43:46Z

src/preamble/01_what_do_we_mean_when_we_say_cabal.md

+   cabal-install and other package managers, stack for example.
+
+3. [cabal-install](#the-binary-cabal-install-cli-tool) is the command line
+   utility to help configure, compile and install Haskell libraries and


I'd change "to help configure" to "for configuring", or something similar, because cabal-install is not a helper that makes it easier. There are no ways to do that except via cabal-inistall.

Mikolaj · 2021-09-27T19:45:01Z

src/preamble/01_what_do_we_mean_when_we_say_cabal.md

+## The .cabal file
+
+The .cabal file contains information that drives the compilation and building of
+Haskell packages. The .cabal file lives at the root directory that contains the


I'm not a native speaker, but I suspect "in root directory".

Mikolaj · 2021-09-27T19:47:00Z

src/preamble/01_what_do_we_mean_when_we_say_cabal.md

+
+The .cabal file contains information that drives the compilation and building of
+Haskell packages. The .cabal file lives at the root directory that contains the
+haskell source code corresponding to the package. By convention this file is


I'd rephrase to "in root directory of the source tree of the package". Root directory does not contain code. It contains other directories that contain code and other directories, etc.

Mikolaj · 2021-09-27T20:16:37Z

src/preamble/01_what_do_we_mean_when_we_say_cabal.md

+cabal-install is a frontend to Cabal. It makes it possible to build Haskell
+projects whose sets of dependencies might conflict with each other within the
+confines of a single system. A package's .cabal file provides a constraint on


This is important point, but hard to get across. Perhaps " It's perfectly comfortable building two Haskell projects whose sets of dependencies are conflicting and storing their artefacts to be concurrently employed by the user."

Mikolaj · 2021-09-27T20:18:50Z

src/preamble/01_what_do_we_mean_when_we_say_cabal.md

+the version of various libraries (version bounds) that they expect. When
+cabal-install is asked to build a project, by default it looks at the
+dependencies specified in its .cabal file and uses a dependency solver to figure
+out a set of packages and package versions that satisfy it. This set of packages


I'd say "packages with their versions" to be able to later on omit "and package versions".

Mikolaj · 2021-09-27T20:19:45Z

src/preamble/01_what_do_we_mean_when_we_say_cabal.md

+cabal-install is asked to build a project, by default it looks at the
+dependencies specified in its .cabal file and uses a dependency solver to figure
+out a set of packages and package versions that satisfy it. This set of packages
+is drawn from Hackage. The chosen versions of the dependenices will be installed


"Hackage (the central Haskell package repository) or another repository specified by the user"; BTW, typo: dependenices

Mikolaj · 2021-09-27T20:20:36Z

src/preamble/01_what_do_we_mean_when_we_say_cabal.md

+
+Conflicts between dependencies are avoided by indexing the installed packages
+according to their version and other relevant configuration options. This allows
+different projects to retrieve the dependency versions they need.


I'd add "dependency versions and build flavours".

Mikolaj · 2021-09-27T20:22:52Z

src/preamble/01_what_do_we_mean_when_we_say_cabal.md

+according to their version and other relevant configuration options. This allows
+different projects to retrieve the dependency versions they need.
+
+stack is also a command-line tool that depends on the Cabal Library, and hence


Let's be high-minded and also compliment ourselves saying something like "stack is another mature command-line tool, with somewhat different goals and trade-offs, that depends...".

Basic skeleton of what do we mean by cabal

0b6b990

Some starter information about the different meanings for the cabal.

Added details about cabal-install, CABAL, .cabal

def8d93

srirajshukla marked this pull request as ready for review August 3, 2021 20:38

JonathanLorimer suggested changes Aug 6, 2021

View reviewed changes

Changes according to suggestions

f9a2929

1. Rewrote about `.cabal` section 2. Changed tl;dr for cabal library and added a bit more about it. 3. Changed inline href from anchor tags to direct linking. 4. Fixed typos.

JonathanLorimer suggested changes Aug 10, 2021

View reviewed changes

Fixed wrong links, reworded some parts.

cd50724

JonathanLorimer reviewed Sep 8, 2021

View reviewed changes

Fixed typos, grammar mistakes, added more info

c4f4fe8

1. Fixed some typos pointed out in code review. 2. Added more information on Haskell implementations.

JonathanLorimer previously approved these changes Sep 9, 2021

View reviewed changes

JonathanLorimer requested a review from Mikolaj September 9, 2021 13:29

jhrcek previously approved these changes Sep 10, 2021

View reviewed changes

srirajshukla added 2 commits September 11, 2021 01:58

Fixed typos, grammar mistakes, added more info

23954b7

1. Fixed some typos pointed out in code review. 2. Added more information on Haskell implementations.

Merge branch 'chapter-01' of https://github.com/srirajshukla/cabal-us…

47c6d8c

…erguide into chapter-01

srirajshukla dismissed jhrcek’s stale review via 47c6d8c September 10, 2021 20:29

srirajshukla dismissed JonathanLorimer’s stale review via 47c6d8c September 10, 2021 20:29

srirajshukla requested a review from JonathanLorimer September 10, 2021 20:31

Mikolaj approved these changes Sep 27, 2021

View reviewed changes

	2. [The Cabal build system](#cabailBuildSystem), a specification for defining
	2. [The Cabal build system](#cabalBuildSystem), a specification for defining

		projects whose sets of dependencies might conflict with each other within the
		confines of a single system. When cabal-install is asked to build a project, by

		@@ -1 +1,96 @@
		# What do we mean when we say cabal?

		Cabal is an umbrella term that can refer to either "cabal the spec" (.cabal

Ch-01 What do we mean when we say cabal? #26

Are you sure you want to change the base?

Ch-01 What do we mean when we say cabal? #26

Conversation

srirajshukla commented Jul 21, 2021

srirajshukla commented Jul 21, 2021

JonathanLorimer commented Jul 21, 2021

srirajshukla commented Aug 3, 2021 • edited

Mikolaj commented Aug 3, 2021

srirajshukla commented Aug 3, 2021

JonathanLorimer commented Aug 6, 2021

JonathanLorimer commented Aug 6, 2021

srirajshukla commented Aug 6, 2021

JonathanLorimer left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

srirajshukla commented Aug 9, 2021

JonathanLorimer commented Aug 9, 2021

Choose a reason for hiding this comment

srirajshukla commented Aug 16, 2021 • edited

srirajshukla commented Sep 2, 2021

JonathanLorimer left a comment

Choose a reason for hiding this comment

srirajshukla commented Sep 8, 2021 • edited

JonathanLorimer commented Sep 9, 2021

Mikolaj commented Sep 9, 2021

jhrcek left a comment

Choose a reason for hiding this comment

jhrcek Sep 10, 2021 • edited

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Mikolaj commented Sep 18, 2021

Mikolaj commented Sep 27, 2021

Mikolaj left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

srirajshukla commented Aug 3, 2021 •

edited

srirajshukla commented Aug 16, 2021 •

edited

srirajshukla commented Sep 8, 2021 •

edited

jhrcek Sep 10, 2021 •

edited