http://hackage.haskell.org
Если для вашей задачи необходимо выполнить какую-нибудь довольно общую задачу, например написать
тип красно-чёрных деревьев или построить парсер или возможно вам нужен веб-сервер, поищите этот пакет
на Hackage, он там наверняка окажется, ещё и в нескольких вариантах.
Для установки пакета с Hackage нужно просто написать
cabal install имя-пакета
Возможно нам нужен очень новый пакет, который был только что залит автором на Hackage. Тогда вы-
полняем:
cabal update
Происходит обновление данных о загруженных на Hackage. Что хорошо, вы можете загрузить исходники
из Hackage, например у вас никак не получается написать пакет, который устанавливался бы без ошибок.
Просто загрузим исходники какого-нибудь пакета из Hackage и посмотрим на пример рабочего пакета.
Пакеты | 269
Дополнительные атрибуты пакета
В файле . cabal также часто указывают такие атрибуты как:
Maintainer Поле содержит адрес электронной почты технической поддержки
Stability Статус версии библиотеки (стабильная, экспериментальная, нестабильная).
Description Подробное описание назначения пакета. Оно помещается на главную страницу пакета в доку-
ментации.
Extra-Source-Files В этом поле можно через пробел указать дополнительные файлы, включаемые в пакет.
Это могут быть примеры использования, описание в формате PDF или хроника изменений и другие
служебные файлы.
License-file Путь к файлу с лицензией.
ghc-options Флаги компиляции для GHC. Если в нашей библиотеке мы активно пользуемся продвинуты-
ми прагмами оптимизации, необходимо сообщить об этом компилятору пользователя. Например, мы
можем написать в этом атрибуте -O или -O2.
Установка библиотек для профилирования
Помните когда-то мы занимались профилированием? Это было в главе, посвящённой устройству GHC.
Мы включали флаг —prof и всё шло гладко. Там мы профилировали код, в котором участвовали лишь
стандартные библиотеки из пакета base, такие как Prelude. Но если мы попробуем профилировать код с
какими-нибудь другими библиотеками, установленными с помощью cabal, GHC возмутится и скажет, что
для профилирования не хватает специальной версии библиотеки имярек. Для того чтобы иметь возможность
профилировать код, в котором участвуют другие библиотеки необходимо установить их с возможностью
профилирования. Это делается при установке с помощью специального флага –“enable-library-profiling
или –“enable-executable-profiling (если мы устанавливаем исполняемое приложение):
$ cabal install имярек —reinstall —enable-library-profiling
Библиотека будет установлена в двух экземплярах: для исполнения и профилирования. Возможно биб-
лиотека имярек потребует переустановки некоторых библиотек, от которых она зависит. Повторяем эту про-
цедуру для этих библиотек и возвращаемся к исходной библиотеке. К сожалению, избежать переустановки
библиотек нельзя. Но мы можем сделать так, чтобы все будущие библиотеки устанавливались с возмож-
ностью профилирования. Для этого необходимо отредактировать файл настроек программы cabal. Ищем
директори, в которой cabal хранит свои служебные файлы. Если вы пользуетесь Linux, то скорее всего это
скрытая директория . cabal в вашей домашней директории. Если вы пользуетесь Windows, положение ди-
ректории зависит от версии системы. Но ничего, узнать её положение можно, выполнив в ghci
Prelude> :m System.Directory
Prelude System.Directory> getAppUserDataDirectory ”cabal”
Присмотритесь к этой директории в ней вы найдёте много полезных данных. В ней находятся испол-
няемые программы, скомпилированные библиотеки, а также исходный код библиотек. В этой директории
находится и файл config с настройками для cabal. Ищем строчку с полем library—profiling: False. Меня-
ем значение на True и раскомментируем эту строчку, если она закомментирована. После этого cabal install
будет устанавливать библиотеки для профилирования. На первых порах это вызовет массу неудобств из-за
необходимости переустановки многих библиотек.
18.2 Создание документации с помощью Haddock
Если мы зайдём на Hackage, то там мы увидим длинный список пакетов, отсортированных по категориям.
К какой категории какой пакет относится мы указываем в . cabal-файле в атрибуте Category. Далее рядом с
именем пакета мы видим краткое описание, оно берётся из атрибута Synopsis. Если мы зайдём на страницу
одного из пакетов, то там мы увидим страницу в таком же формате, что и документация к стандартным
библиотекам. Мы видим описание пакета и ниже иерархию модулей. Мы можем зайти в заинтересовавший
нас модуль и посмотреть на объявленные функции, типы и классы. В самом низу страницы находится ссылка
к исходникам пакета.
“Домашняя страница” пакета была создана с помощью приложения Haddock. Оно генерирует документа-
цию в формате html по специальным комментариям. Haddock встроен в cabal, например мы можем сделать
документацию к нашему пакету hello. Для этого нужно переключиться на корневую директорию пакета и
вызвать:
270 | Глава 18: Средства разработки
cabal haddock
После этого в директории dist появится директория doc, в которой внутри директории html находится
созданная документация. Мы можем открыть файл index. html и там мы увидим “иерархию нашего” модуля.
В модуле пока нет ни одной функции, так получилось потому, что Haddock помещает в документацию лишь
те функции, у которых есть объявление типа. Если мы добавим в модуле Hello. hs: к единственной функции
объявление типа:
helloWorld :: String
helloWorld = hello ++ ”, ” ++ world ++ ”!”
И теперь перезапустим haddock. То мы увидим, что в модуле Hello появилась одна запись.
Комментарии к определениям
Прокомментировать любое определение можно с помощью комментария следующего вида:
— | Here is the comment
helloWorld :: String
helloWorld = hello ++ ”, ” ++ world ++ ”!”
Обратите внимание на значок “или”, сразу после комментариев. Этот комментарий будет включен в
документацию. Также можно писать комментарии после определения для этого к комментарию добавляется
значок степени:
helloWorld :: String
helloWorld = hello ++ ”, ” ++ world ++ ”!”
— ^ Here is the comment
К сожалению на момент написания этих строк Haddock может включать в документацию лишь латинские
символы. Комментарии могут простираться несколько строк:
— | Here is the type.
— It contains three elements.
— That’s it.
data T = A | B | C
Также они могут быть блочными:
Here is the type.
It contains three elements.
That’s it.
—
data T = A | B | C
Мы можем комментировать не только определение целиком, но и отдельные части. Например так мы
можем пояснить отдельные аргументы у функции:
add :: Num a => a
— ^ The first argument
-> a
— ^ The second argument
-> a
— ^ The return value
Методы класса и отдельные конструкторы типа можно комментировать как обычные функции:
data T
— | constructor A
= A
— | constructor B
| B
— | constructor C
| C
Или так:
Создание документации с помощью Haddock | 271
data T = A
— ^ constructor A
| B
— ^ constructor B
| C
— ^ and so on
Комментарии к классу:
— | С-class
class С a where
— | f-function
f :: a -> a
— | g-function
g :: a -> a
Комментарии к модулю
Комментарии к модулю помещаются перед объявлением имени модуля. Эта информация попадёт в самое
начало страницы документации:
