Tuesday, March 29, 2016

Publish a Haskell package in Hackage

Haskell being in the 38th position in the Programming Community Index, it has an immense number of packages providing a variety of functionalities for its developers. You can find the full list of Haskell packages in here. Even though, there are such a huge number of packages many new packages are added to Hackage frequently. 

First, let's understand what does it mean by 'package' in Haskell. A package is the unit of distribution for the Cabal, which is a system for building and packaging Haskell libraries and programs. Its purpose in life, when installed, is to make available some Haskell modules to be imported into a Haskell program a developer is writing.

Before starting off with package development, you need to understand couple of basic rules and regulations in a Haskell package. The main concern in developing a package is that, it should be light-weighted as much as possible, i.e. the build depends section in the cabal file should contain minimal dependencies to the other packages. And the other main thing, you need to be aware of is the documentation. Use 'Haddock' to build the necessary documentation of your package. Refer to this link to read more on the Haddock usage in your Haskell package.

Now that you have a basic understanding about the Haskell packages, let's get to work! 

First step is to make sure your program compiles without any errors. And then, it provides the expected output when run with the desired input parameters. 

Then, create a comprehensive cabal file for your package. You can create a cabal file for your project by running 'cabal init' in your terminal at the project directory. Once you have the basic structure, fill in the required fields of the cabal file using a text editor. After filling out fields, you can check whether your cabal file is correct by running 'cabal check' in the terminal. If there are any missing fields, this command will point out them to you.

After that, use Haddock to build the necessary documentation for the code. To do this, you can type in 'cabal haddock' in your terminal after navigating to the project directory. This command will output the document coverage of the code and points out the necessary places, which need to be updated.


If you don't have any idea how to create a comprehensive documentation for your package, just take a look at the available packages in Hackage and adapt those documentation styles to your package. 

The next step is to create the tarball of your package content. First get your code, cabal file, README file and put them in a folder with the name package-version. For an example; foo-0.1.3.0. You can read more about the package version policy in Haskell in this link
Since I'm using Windows, I used 7-Zip to create a tarball. Following the instructions in their you can create the tarball for you package.

Then comes the part, where you upload the package to Hackage. In order to upload a package, you must have an account. You have to request an account by filling out the form in this link. Once you have your account, log into your account.

There are 2 package upload scenarios; upload a new package OR upload a new version of an existing package.

Scenario 1: Upload a new package.

You can simply go to the upload link in your account, and click on 'Upload a package' leading you here. You can upload you tarball here, and if there are no errors in your tarball structure this will upload the package candidate smoothly. Then go your user-account. Now you can see the uploaded package. If you can't find a link to go to your account, just search your username in the user-accounts list here

Now go to your package and go to 'Maintainer's corner' and click on 'edit package information' which will take you to the publishing page as shown below;















Now you can publish the candidate by clicking on 'Publish candidate', making the package available for the other Haskell developers. 

Scenario 2: Upload a new version of an existing package

In order to do this you should be part of the maintainer group of the package. Given that you are in the maintainer group, you can upload a package candidate following the above steps. But the most important thing to remember is that, you cannot upload the same version number again to Hackage.

There are many resources available in the internet, you can read to get a thorough understanding on the matter. Please do read and understand the procedure before you publish your package, because you can upload a package version once!

No comments:

Post a Comment