Savelenko · June 14, 2024 17:22 · Sep 10, 2019 · Sep 10, 2019 · Sep 10, 2019 · Sep 10, 2019
diff --git a/cabal.rst b/cabal.rst
@@ -53,7 +53,7 @@ plan satisfying the version constraints, then compiles using this build plan.
 various package versions on Stackage and dependencies are resolved by "just use
 the exact version specified by the resolver".
 
-It is possible to make ``stack`` resolve things dynamically[1]_ as
+It is possible to make ``stack`` resolve things dynamically [1]_ as
 ``cabal-install`` and vice versa, you can create snapshots (freeze files) using
 ``cabal-install`` to accomplish what ``stack`` does.
 

diff --git a/cabal.rst b/cabal.rst
@@ -1,11 +1,3 @@
-.. |ss| raw:: html
-
-   <strike>
-
-.. |se| raw:: html
-
-   </strike>
-
 ====================================
 The Cabal/Stack Disambiguation Guide
 ====================================
@@ -61,8 +53,8 @@ plan satisfying the version constraints, then compiles using this build plan.
 various package versions on Stackage and dependencies are resolved by "just use
 the exact version specified by the resolver".
 
-|ss|It is possible to make ``stack`` resolve things dynamically as
-``cabal-install`` and vice versa,|se|[1]_ you can create snapshots (freeze files) using
+It is possible to make ``stack`` resolve things dynamically[1]_ as
+``cabal-install`` and vice versa, you can create snapshots (freeze files) using
 ``cabal-install`` to accomplish what ``stack`` does.
 
 So which tool should I use?

diff --git a/cabal.rst b/cabal.rst
@@ -1,3 +1,11 @@
+.. |ss| raw:: html
+
+   <strike>
+
+.. |se| raw:: html
+
+   </strike>
+
 ====================================
 The Cabal/Stack Disambiguation Guide
 ====================================
@@ -73,12 +81,4 @@ potential users to install extra tooling. The ``.cabal`` format is understood
 by both ``cabal-install`` and ``stack`` without extra tools, so everyone can
 just use/contribute with their preferred tools.
 
-.. [1] As of Stack 2.x this functionality has been dropped from Stack and so this is no longer possible.
-
-.. |ss| raw:: html
-
-   <strike>
-
-.. |se| raw:: html
-
-   </strike>
+.. [1] As of Stack 2.x this functionality has been dropped from Stack and so this is no longer possible.
diff --git a/cabal.rst b/cabal.rst
@@ -53,8 +53,8 @@ plan satisfying the version constraints, then compiles using this build plan.
 various package versions on Stackage and dependencies are resolved by "just use
 the exact version specified by the resolver".
 
-It is possible to make ``stack`` resolve things dynamically as
-``cabal-install`` and vice versa, you can create snapshots (freeze files) using
+|ss|It is possible to make ``stack`` resolve things dynamically as
+``cabal-install`` and vice versa,|se|[1]_ you can create snapshots (freeze files) using
 ``cabal-install`` to accomplish what ``stack`` does.
 
 So which tool should I use?
@@ -71,4 +71,14 @@ the past there were some (in my personal opinion, weak) reasons for using
 ``package.yaml`` does not support all CABAL features and requires all your
 potential users to install extra tooling. The ``.cabal`` format is understood
 by both ``cabal-install`` and ``stack`` without extra tools, so everyone can
-just use/contribute with their preferred tools.
+just use/contribute with their preferred tools.
+
+.. [1] As of Stack 2.x this functionality has been dropped from Stack and so this is no longer possible.
+
+.. |ss| raw:: html
+
+   <strike>
+
+.. |se| raw:: html
+
+   </strike>
diff --git a/cabal.rst b/cabal.rst
@@ -0,0 +1,74 @@
+====================================
+The Cabal/Stack Disambiguation Guide
+====================================
+
+One of the most frequently asked Haskell beginner questions in recent years is:
+
+    "Stack or cabal?"
+
+I will helpfully **not** answer this question. Instead I will hope to eliminate
+the confusion that many of the askers seem to have about the various different
+things named "cabal" and how they relate to each other and stack.
+
+So, how many things named "cabal" do we have? We have:
+
+1. CABAL (the spec)
+
+   CABAL is the Common Architecture for Building Applications & Libraries. It's
+   a specification for defining how Haskell applications and libraries should
+   be built, defining dependencies, etc.
+
+2. ``.cabal`` (the file format)
+
+   The file format used to write down the aforementioned definitions for a
+   specific package.
+
+3. Cabal (the library)
+
+   The library implementing the above specification and file format.
+
+4. ``cabal`` (the executable)
+
+   The ``cabal`` executable, more accurately named ``cabal-install``, is a
+   commandline tool that uses Cabal (the library) to resolve dependencies from
+   Hackage and build packages.
+
+
+How does Stack relate to all this CABAL stuff?
+==============================================
+
+Stack is a replacement for ``cabal-install``, i.e. the ``cabal`` executable.
+The ``stack`` commandline tool, like ``cabal-install`` is a tool that uses
+Cabal (the library) to resolve dependencies and build packages. The main
+difference between ``cabal-install`` and ``stack`` is how they resolve
+dependencies.
+
+So, what do ``cabal-install`` and ``stack`` do differently?
+
+``cabal-install`` looks at the declared version ranges of a package in the
+``.cabal`` file and using the available versions on Hackage it computes a build
+plan satisfying the version constraints, then compiles using this build plan.
+
+``stack`` on the other hand uses "resolvers". A resolver is a snapshot of
+various package versions on Stackage and dependencies are resolved by "just use
+the exact version specified by the resolver".
+
+It is possible to make ``stack`` resolve things dynamically as
+``cabal-install`` and vice versa, you can create snapshots (freeze files) using
+``cabal-install`` to accomplish what ``stack`` does.
+
+So which tool should I use?
+===========================
+
+Honestly, at this point I don't think there is much difference, use whichever
+tool best fits your workflow. The only real strong opinion I have is that you
+should avoid Stack's (optional) use of ``hpack`` at all costs.
+
+``hpack`` is a tool that generates ``.cabal`` files from ``package.yaml``. In
+the past there were some (in my personal opinion, weak) reasons for using
+``package.yaml``, but those are nowadays possible in ``.cabal`` too.
+
+``package.yaml`` does not support all CABAL features and requires all your
+potential users to install extra tooling. The ``.cabal`` format is understood
+by both ``cabal-install`` and ``stack`` without extra tools, so everyone can
+just use/contribute with their preferred tools.
No results found