Using cabal (with examples)
1: Searching and listing packages from Hackage
To search and list packages from the Hackage package repository, you can use the cabal list command followed by a search string. This allows you to find relevant packages based on specific keywords or names.
cabal list search_string
Motivation: This command is useful when you want to explore the available Haskell packages on Hackage and find packages that might be relevant to your project. It saves you time from manually browsing through the Hackage website.
Explanation: Replace search_string with the keyword or partial name of the package you want to search for. Cabal will then retrieve the list of packages matching your search criteria.
Example: Searching for packages related to “web” can be done with the following command:
cabal list web
Example output:
pandoc-web-0.1.3.3
web-api-1.3.1.0
web-app-0.2.3.1
...
2: Showing information about a package
To obtain detailed information about a specific package, you can use the cabal info command followed by the package name. This command provides you with information such as the package version, license, maintainer, and more.
cabal info package
Motivation: This command is useful when you want to learn more about a package before deciding to use it in your project. It allows you to gather information about the package’s compatibility, popularity, and maintainability.
Explanation: Replace package with the name of the package you want to retrieve information about. Cabal will then fetch and display the details of the specified package.
Example: To get information about the QuickCheck package, you can use the following command:
cabal info QuickCheck
Example output:
* QuickCheck
Synopsis: Automatic testing of Haskell programs
Latest version: 2.14.2
...
License: BSD-3-Clause
Maintainer: quickcheck@haskell.org
...
3: Downloading and installing a package
To download and install a package from Hackage, you can use the cabal install command followed by the package name. This command fetches the specified package and installs it in your local environment, making it available for use in your Haskell projects.
cabal install package
Motivation: This command is essential when you want to add a new package to your project to leverage its functionality. It automatically handles the download, installation, and dependency management for the specified package.
Explanation: Replace package with the name of the package you want to install. Cabal will retrieve the package from Hackage, download it, and install it in your local environment.
Example: To install the aeson package, you can use the following command:
cabal install aeson
Example output:
...
Installed aeson-1.5.6.0
...
4: Creating a new Haskell project
To create a new Haskell project in the current directory, you can use the cabal init command. This command initializes a new Cabal project by generating the required project files and structure, including the .cabal file.
cabal init
Motivation: This command is useful when you want to start a new Haskell project from scratch. It saves you time from manually creating the project structure and generating the necessary files.
Explanation: Simply execute the cabal init command in the desired directory. Cabal will interactively guide you through the process of creating the project by asking questions about the project’s name, version, dependencies, and other project-specific details.
Example: Running cabal init command will prompt you with a series of questions to configure your project.
Example output:
Package name? [default: my-project]
...
Author name? [default: John Doe]
...
License? (see <https://spdx.org/licenses/> for common options) [default: BSD3]
...
5: Building a Haskell project
To build a Haskell project in the current directory, you can use the cabal build command. This command compiles the project’s source code and generates the executable or library artifacts specified in the project’s .cabal file.
cabal build
Motivation: This command is essential when you want to compile and build your Haskell project. It ensures that your project’s code is successfully compiled and ready for execution or distribution.
Explanation: Simply execute the cabal build command in the root directory of your project. Cabal will read the .cabal file and compile the project’s source code, generating the output artifacts based on your project’s configuration.
Example: Running cabal build command will compile the project and generate the necessary artifacts.
Example output:
Preprocessing library 'my-project' for my-project-1.0...
...
[1 of 3] Compiling Module1 ( src/Module1.hs, dist/build/Module1.o )
...
Linking my-project-1.0...
6: Running tests of a Haskell project
To run tests of a Haskell project in the current directory, you can use the cabal test command. This command executes the test cases specified in the project’s test suite(s) and reports the test results.
cabal test
Motivation: This command is useful when you want to validate the correctness of your Haskell project by running the defined test cases. It ensures that your project behaves as expected and does not introduce any regressions.
Explanation: Executing the cabal test command triggers the test suite defined in your project’s .cabal file. Cabal automatically runs the specified test cases and provides a detailed report indicating the pass or fail status of each test case.
Example: Running cabal test command will execute the test suite and display the test results.
Example output:
Running 5 test cases...
Cases: 5 Tried: 5 Errors: 0 Failures: 0
Conclusion
In this article, we explored various use cases of the cabal command-line tool, which is essential for managing Haskell projects and packages. We covered how to search and list packages from Hackage, obtain package information, download and install packages, create new Haskell projects, build projects, and run tests. Understanding and utilizing these commands will greatly facilitate the development process and help you harness the power of the Haskell ecosystem.
