5.9. Пакеты

5.9.1. Использование пакетов

GHC знает только об установленных пакетах. Установленные пакеты хранятся в базах данных пакетов. Подробные сведения о базах данных пакетов и о том, как управлять тем, какие базы данных пакетов или конкретные наборы пакетов доступны GHC, см. в разделе Базы данных пакетов.

Чтобы посмотреть, какие пакеты доступны в данный момент, используйте команду ghc-pkg list:

$ ghc-pkg list
/usr/lib/ghc-6.12.1/package.conf.d:
    Cabal-1.7.4
    array-0.2.0.1
    base-3.0.3.0
    base-4.2.0.0
    bin-package-db-0.0.0.0
    binary-0.5.0.1
    bytestring-0.9.1.4
    containers-0.2.0.1
    directory-1.0.0.2
    (dph-base-0.4.0)
    (dph-par-0.4.0)
    (dph-prim-interface-0.4.0)
    (dph-prim-par-0.4.0)
    (dph-prim-seq-0.4.0)
    (dph-seq-0.4.0)
    extensible-exceptions-0.1.1.0
    ffi-1.0
    filepath-1.1.0.1
    (ghc-6.12.1)
    ghc-prim-0.1.0.0
    haskeline-0.6.2
    haskell98-1.0.1.0
    hpc-0.5.0.2
    integer-gmp-0.1.0.0
    mtl-1.1.0.2
    old-locale-1.0.0.1
    old-time-1.0.0.1
    pretty-1.0.1.0
    process-1.0.1.1
    random-1.0.0.1
    rts-1.0.1
    syb-0.1.0.0
    template-haskell-2.4.0.0
    terminfo-0.3.1
    time-1.1.4
    unix-2.3.1.0
    utf8-string-0.3.4

Установленный пакет по умолчанию либо открыт, либо скрыт. Пакеты, скрытые по умолчанию, перечислены в скобках (например, (lang-1.0)) или, если ваш терминал поддерживает цвет, выделены синим цветом в выводе ghc-pkg list. Описанные ниже флаги командной строки позволяют открыть скрытый пакет или скрыть открытый. В коде Haskell можно импортировать только модули из открытых пакетов; если вы попытаетесь импортировать модуль из скрытого пакета, GHC выдаст сообщение об ошибке. Следует отметить, что скрытый пакет всё ещё может быть слинкован с вашей программой как зависимость открытого пакета — ограничивается только прямой импорт его модулей.

Если открыто несколько версий пакета, GHC отдаст предпочтение самой поздней. Кроме того, некоторые пакеты могут быть неисправны: например, они отсутствуют в базе данных пакетов или неисправна одна из их зависимостей; в этом случае такие пакеты исключаются из набора пакетов по умолчанию.

Подобно статусу скрытия пакета, существует статус доверия пакету. Пакет может быть доверенным или недоверенным (отвергнутым). По умолчанию пакеты считаются недоверенными. Это свойство пакета имеет значение только при компиляции кода с использованием функции GHC Safe Haskell (см. раздел Safe Haskell) с включённым флагом -fpackage-trust.

Чтобы посмотреть, какие модули предоставляет пакет, используйте команду ghc-pkg (см. раздел Управление пакетами (команда ghc-pkg)):

$ ghc-pkg field network exposed-modules
exposed-modules: Network.BSD,
                 Network.CGI,
                 Network.Socket,
                 Network.URI,
                 Network

Параметры командной строки GHC, управляющие пакетами:

-package ⟨pkg⟩

Этот параметр открывает установленный пакет ⟨pkg⟩. Пакет ⟨pkg⟩ можно указать полностью, вместе с номером версии (например, network-1.0), либо опустить номер версии — в этом случае GHC автоматически откроет самую позднюю исправную версию из установленных версий пакета.

По умолчанию (если не указан -hide-all-packages) GHC открывает только одну версию пакета, а все остальные версии становятся скрытыми. Если параметр -package указан несколько раз для одного и того же пакета, последний параметр переопределяет предыдущие. С другой стороны, если используется -hide-all-packages, GHC позволяет открыть несколько версий пакета, указав параметр -package несколько раз с разными версиями одного пакета.

Параметр -package поддерживает сокращение списка модулей и их переименование, описанные в разделе Сокращение списка и переименование модулей.

Параметр -package ⟨pkg⟩ также приводит к тому, что пакет ⟨pkg⟩ линкуется с полученным исполняемым файлом или разделяемым объектом. Статическая или динамическая линковка библиотеки пакета определяется парой флагов -static/ -dynamic.

В режиме --make и режиме --interactive (см. раздел Режимы работы) компилятор обычно определяет, какие пакеты требуются текущим модулям Haskell, и линкует только их. Однако в пакетном режиме информация о зависимостях недоступна, поэтому при линковке необходимо явно указывать параметры -package. Ещё один случай, когда может понадобиться использовать -package для принудительной линковки пакета, — пакет не содержит модулей Haskell (например, в нём может быть только библиотека C). В этом случае GHC не сможет обнаружить зависимость от него, поэтому его необходимо указать явно.

Например, чтобы слинковать программу, состоящую из объектных файлов Foo.o и Main.o, в которой используется пакет network, необходимо передать GHC флаг -package следующим образом:

$ ghc -o myprog Foo.o Main.o -package network

Этот же флаг необходим, даже если мы скомпилировали модули из исходного кода, поскольку GHC всё ещё считает, что работает в пакетном режиме:

$ ghc -o myprog Foo.hs Main.hs -package network

-package-id ⟨unit-id⟩

Открывает пакет, как и -package ⟨pkg⟩, но пакет указывается по его идентификатору unit (то есть по значению id в его записи в базе данных установленных пакетов, ранее также называвшемуся идентификатором установленного пакета), а не по имени. Это более надёжный способ указания пакетов, позволяющий выбирать пакеты, которые в противном случае были бы затенены. Cabal передаёт GHC флаги -package-id. Параметр -package-id поддерживает сокращение списка модулей и их переименование, описанные в разделе Сокращение списка и переименование модулей.

-hide-all-packages

Игнорирует флаг открытости установленных пакетов и скрывает их все по умолчанию. Если вы используете этот флаг, все необходимые вам пакеты (включая base) нужно явно открыть с помощью параметров -package ⟨pkg⟩.

Это хороший способ защитить программу от различий в глобально открытых пакетах, а явное указание зависимостей пакета — это полезная практика. Cabal всегда передаёт GHC флаг -hide-all-packages именно по этой причине.

-hide-package ⟨pkg⟩

Этот параметр действует противоположно параметру -package ⟨pkg⟩: он скрывает указанный пакет, то есть ни один его модуль нельзя будет импортировать с помощью директив Haskell import.

Обратите внимание, что пакет всё ещё может быть слинкован с итоговой программой, если он является прямой или косвенной зависимостью другого открытого пакета.

-ignore-package ⟨pkg⟩

Заставляет компилятор вести себя так, как если бы пакет ⟨pkg⟩ и все зависящие от него пакеты вообще не были установлены.

Указание -ignore-package ⟨pkg⟩ равносильно указанию флагов -hide-package ⟨pkg⟩ для пакета ⟨pkg⟩ и всех зависящих от него пакетов. Иногда заранее неизвестно, какие установленные пакеты зависят от ⟨pkg⟩; в таких случаях может быть полезен флаг -ignore-package ⟨pkg⟩.

-no-auto-link-packages

По умолчанию GHC автоматически линкует пакеты base, ghc-internal и rts. Этот флаг отключает такое поведение.

Идентификатор unit автоматически линкуемого пакета base можно задать с помощью флага -base-unit-id ⟨unit-id⟩.

-base-unit-id ⟨unit-id⟩

По умолчанию компилятор линкуется с пакетами base, ghc-internal и rts; этот флаг задаёт, с каким пакетом base будет выполнена линковка.

Передавать этот флаг нужно только в том случае, если вы точно знаете, что делаете. Дистрибутивы могут задать идентификатор unit по умолчанию для base во время установки, указав переменную среды BASE_UNIT_ID.

-this-unit-id ⟨unit-id⟩

Сообщает GHC, что компилируемый модуль является частью идентификатора unit ⟨unit-id⟩; внутри системы эти ключи используются для определения равенства типов и символов компоновщика. Начиная с GHC 8.0 идентификаторы unit могут состоять только из буквенно-цифровых символов, дефисов, подчёркиваний и точек. В будущих выпусках GHC оставляет за собой право придавать другим символам специальное значение.

-trust ⟨pkg⟩

Этот параметр открывает установленный пакет ⟨pkg⟩ и помечает его как доверенный для GHC. Эта команда работает почти так же, как команда -package ⟨pkg⟩, но дополнительно помечает выбранные пакеты как доверенные для GHC независимо от содержимого базы данных пакетов (см. раздел Safe Haskell).

-distrust ⟨pkg⟩

Этот параметр открывает установленный пакет ⟨pkg⟩ и помечает его как недоверенный для GHC. Эта команда работает почти так же, как команда -package ⟨pkg⟩, но дополнительно помечает выбранные пакеты как недоверенные для GHC независимо от содержимого базы данных пакетов (см. раздел Safe Haskell).

-distrust-all-packages

Игнорирует флаг доверия установленных пакетов и по умолчанию считает их недоверенными. Если вы используете этот флаг и Safe Haskell, то все пакеты, которым вы доверяете (включая base), необходимо явно пометить как доверенные с помощью параметров -trust ⟨pkg⟩. Этот параметр не меняет статус пакета — открытый он или скрытый, поэтому он не равнозначен применению параметра -distrust ⟨pkg⟩ ко всем пакетам в системе (см. раздел Safe Haskell).

5.9.2. Пакет main

Каждая полноценная программа на Haskell должна определять main в модуле Main пакета main. Если не указать флаг -this-unit-id ⟨unit-id⟩, код будет скомпилирован для пакета main. В противном случае во время линковки возникнет довольно невразумительная ошибка следующего вида:

/usr/bin/ld: Undefined symbols:
_ZCMain_main_closure

5.9.3. Последствия использования пакетов для языка Haskell

При использовании пакетов в программе могут оказаться два модуля с одинаковыми именами: возможно, вы использовали пакет P, содержащий скрытый модуль M, а в вашей программе также есть модуль M. Или, возможно, зависимости используемых вами пакетов содержат некоторые совпадающие модули. Возможно, программа даже содержит несколько версий одного пакета из-за зависимостей других пакетов.

Сами по себе ни один из этих сценариев не приводит к ошибке [1], но они могут иметь интересные последствия. Например, если у вас есть тип M.T из версии 1 пакета P, то он не является тем же типом, что и M.T из версии 2 пакета P, и GHC выдаст ошибку, если вы попытаетесь использовать один тип там, где ожидается другой.

Формально говоря, в Haskell 98 сущность (функция, тип или класс) в программе однозначно определяется парой: именем модуля, в котором она определена, и её именем. В GHC сущность однозначно определяется тройкой: пакет, модуль и имя.

5.9.4. Сокращение списка и переименование модулей

При подключении пакетов из нескольких источников может возникнуть ситуация, когда несколько пакетов предоставляют модули с одинаковыми именами. Раньше различать эти модули можно было только с помощью импортов с указанием пакета. Однако начиная с GHC 7.10 флаги -package ⟨pkg⟩ (и их варианты) были расширены: теперь пользователь может явно указать, какие модули пакета будут доступны, по аналогии со списками импорта, которые можно указывать при импорте модулей.

Вместо того чтобы указывать в параметре пакета -package только имя пакета P, можно указать имя пакета и заключённый в скобки список имён модулей, разделённых запятыми. Например, -package "base (Data.List, Data.Bool)" делает видимыми из пакета base только модули Data.List и Data.Bool. Поддерживается также переименование модулей, если вам нужно одновременно обращаться к обоим модулям; для этого используется запись OldModName as NewModName, например -package "base (Data.Bool as Bool). Можно также написать -package "base with (Data.Bool as Bool), чтобы включить все исходные связи (то есть переименование только добавляет новые имена). Важно указывать кавычки, чтобы оболочка передала имя пакета и список сокращения/переименования как один аргумент GHC.

Импорт пакета с сокращением списка/переименованием не скрывает другие версии пакета: например, если containers-0.9 уже открыт, -package "containers-0.8 (Data.List as ListV8)" лишь добавит дополнительную связь в окружение. Аналогично, -package "base (Data.Bool as Bool)" -package "base (Data.List as List)" равнозначно -package "base (Data.Bool as Bool, Data.List as List)". Буквальные имена должны соответствовать модулям, определённым в исходном пакете, поэтому, например, -package "base (Data.Bool as Bool, Bool as Baz)" недопустимо, если в исходном пакете не был определён модуль Bool. При скрытии пакета также удаляются все его переименования.

Переименование можно использовать для предоставления альтернативного Prelude, например -hide-all-packages -package "basic-prelude (BasicPrelude as Prelude)", вместо расширения Переназначаемый синтаксис и неявный импорт Prelude.

5.9.5. Базы данных пакетов

База данных пакетов хранит сведения об установленных пакетах. Это каталог, обычно называемый package.conf.d, содержащий файл для каждого пакета и двоичный кэш данных пакетов в файле package.cache. Обычно вам не нужно просматривать или изменять содержимое базы данных пакетов напрямую; управлять базами данных пакетов можно с помощью инструмента ghc-pkg (см. раздел Управление пакетами (команда ghc-pkg)).

GHC использует, в частности, две базы данных пакетов:

• Глобальная база данных пакетов, поставляемая вместе с установкой GHC, например /usr/lib/ghc-6.12.1/package.conf.d.
• Пользовательская база данных пакетов, личная для каждого пользователя. В Unix-системах это будет $XDG_DATA_HOME/ghc/arch-os-version/package.conf.d, а в Windows — что-то вроде C:\Documents And Settings\user\ghc\package.conf.d. Инструмент ghc-pkg знает, где должен находиться этот файл, и создаст его, если он отсутствует (см. раздел Управление пакетами (команда ghc-pkg)).

Стек баз данных пакетов: Базы данных пакетов организованы в виде стека. При запуске GHC добавляет в стек глобальную и пользовательскую базы данных пакетов именно в таком порядке, если не задана переменная GHC_PACKAGE_PATH. Если задана переменная GHC_PACKAGE_PATH, она определяет начальный стек баз данных. Несколько описанных ниже параметров командной строки могут дополнительно изменять этот начальный стек. Эффективный стек баз данных пакетов GHC можно посмотреть, запустив GHC с флагом -v.

Из этой структуры стека следует, что порядок флагов -package-db ⟨file⟩ или значений GHC_PACKAGE_PATH имеет значение. Каждый подстек должен быть корректно сформирован (пакеты в базах данных, расположенных выше в стеке, могут ссылаться на пакеты ниже, но не наоборот).

Затенение пакетов: При использовании нескольких баз данных пакетов иногда, хотя и редко, один и тот же идентификатор установленного пакета может присутствовать более чем в одной базе данных. В этом случае пакеты, расположенные ближе к вершине стека, переопределяют ( затеняют) пакеты ниже. Если конфликтующие пакеты оказываются эквивалентными (при сравнении ABI-хеша), один из них заменяет все ссылки на другой; в противном случае переопределённый пакет и все зависящие от него пакеты удаляются.

Выбор версии пакета: При выборе пакета GHC ищет пакеты во всех доступных базах данных. Если доступны несколько версий одного пакета, будет выбрана самая поздняя исправная версия.

Разрешение конфликтов версий: Если доступно несколько экземпляров выбранной GHC версии пакета, GHC выберет один из них без определённого порядка.

Управлять стеком баз данных пакетов GHC можно с помощью следующих параметров:

-package-db ⟨file⟩

Добавляет базу данных пакетов ⟨file⟩ на вершину текущего стека.

-no-global-package-db

Удаляет глобальную базу данных пакетов из стека.

-no-user-package-db

Запрещает загрузку локальной пользовательской базы данных пакетов в начальный стек.

-clear-package-db

Сбрасывает текущий стек баз данных пакетов. Этот параметр удаляет из стека все ранее указанные базы данных пакетов (включая базы данных, заданные переменной среды GHC_PACKAGE_PATH).

-global-package-db

Добавляет глобальную базу данных пакетов на вершину текущего стека. Этот параметр можно использовать после -no-global-package-db, чтобы указать место в стеке, куда следует загрузить глобальную базу данных пакетов.

-user-package-db

Добавляет пользовательскую базу данных пакетов на вершину текущего стека. Этот параметр можно использовать после -no-user-package-db, чтобы указать место в стеке, куда следует загрузить пользовательскую базу данных пакетов.

clear-package-db
global-package-db
user-package-db
package-db db.d/
package-id id_1
package-id id_2
...
package-id id_n

-hide-all-packages
-clear-package-db
-global-package-db
-user-package-db
-package-db db.d/
-package-id id_1
-package-id id_2
...
-package-id id_n

5.9.6. Идентификаторы установленных пакетов, зависимости и повреждённые пакеты

У каждого установленного пакета есть уникальный идентификатор («идентификатор установленного пакета»), который отличает его от всех остальных пакетов, установленных в системе. Чтобы увидеть идентификаторы установленных пакетов, соответствующие каждому установленному пакету, используйте ghc-pkg list -v:

$ ghc-pkg list -v
using cache: /usr/lib/ghc-6.12.1/package.conf.d/package.cache
/usr/lib/ghc-6.12.1/package.conf.d
   Cabal-1.7.4 (Cabal-1.7.4-48f5247e06853af93593883240e11238)
   array-0.2.0.1 (array-0.2.0.1-9cbf76a576b6ee9c1f880cf171a0928d)
   base-3.0.3.0 (base-3.0.3.0-6cbb157b9ae852096266e113b8fac4a2)
   base-4.2.0.0 (base-4.2.0.0-247bb20cde37c3ef4093ee124e04bc1c)
   ...

Строка в скобках после имени пакета — это идентификатор установленного пакета: обычно она начинается с имени и версии пакета и заканчивается строкой хеша, полученной из скомпилированного пакета. Зависимости между пакетами выражаются через идентификаторы установленных пакетов, а не только через имена пакетов и версии. Например, посмотрите на зависимости пакета haskell98:

$ ghc-pkg field haskell98 depends
depends: array-0.2.0.1-9cbf76a576b6ee9c1f880cf171a0928d
         base-4.2.0.0-247bb20cde37c3ef4093ee124e04bc1c
         directory-1.0.0.2-f51711bc872c35ce4a453aa19c799008
         old-locale-1.0.0.1-d17c9777c8ee53a0d459734e27f2b8e9
         old-time-1.0.0.1-1c0d8ea38056e5087ef1e75cb0d139d1
         process-1.0.1.1-d8fc6d3baf44678a29b9d59ca0ad5780
         random-1.0.0.1-423d08c90f004795fd10e60384ce6561

Назначение идентификатора установленного пакета — обнаруживать проблемы, возникающие при повторной установке пакета без перекомпиляции зависящих от него пакетов. Перекомпиляция зависимостей необходима, поскольку у заново скомпилированного пакета может отличаться ABI (двоичный интерфейс приложения) от предыдущей версии, даже если оба пакета были собраны из одного исходного кода с помощью одного и того же компилятора. Благодаря идентификаторам установленных пакетов перекомпилированный пакет получит идентификатор, отличный от идентификатора предыдущей версии, поэтому пакеты, зависевшие от предыдущей версии, теперь становятся осиротевшими — одна из их зависимостей не удовлетворена. Пакеты, повреждённые таким образом, отображаются в выводе ghc-pkg list красным цветом (если это возможно) или, в противном случае, в фигурных скобках. В следующем примере мы перекомпилировали и переустановили пакет filepath, из-за чего нарушились различные зависимости, в том числе зависимость Cabal:

$ ghc-pkg list
WARNING: there are broken packages.  Run 'ghc-pkg check' for more details.
/usr/lib/ghc-6.12.1/package.conf.d:
    {Cabal-1.7.4}
    array-0.2.0.1
    base-3.0.3.0
    ... etc ...

Кроме того, ghc-pkg list напоминает о наличии повреждённых пакетов и предлагает выполнить ghc-pkg check, которая выводит дополнительную информацию о характере сбоя:

$ ghc-pkg check
There are problems in package ghc-6.12.1:
  dependency "filepath-1.1.0.1-87511764eb0af2bce4db05e702750e63" doesn't exist
There are problems in package haskeline-0.6.2:
  dependency "filepath-1.1.0.1-87511764eb0af2bce4db05e702750e63" doesn't exist
There are problems in package Cabal-1.7.4:
  dependency "filepath-1.1.0.1-87511764eb0af2bce4db05e702750e63" doesn't exist
There are problems in package process-1.0.1.1:
  dependency "filepath-1.1.0.1-87511764eb0af2bce4db05e702750e63" doesn't exist
There are problems in package directory-1.0.0.2:
  dependency "filepath-1.1.0.1-87511764eb0af2bce4db05e702750e63" doesn't exist

The following packages are broken, either because they have a problem
listed above, or because they depend on a broken package.
ghc-6.12.1
haskeline-0.6.2
Cabal-1.7.4
process-1.0.1.1
directory-1.0.0.2
bin-package-db-0.0.0.0
hpc-0.5.0.2
haskell98-1.0.1.0

Чтобы исправить проблему, нужно перекомпилировать повреждённые пакеты с учётом новых зависимостей. Проще всего сделать это с помощью cabal-install или загрузить пакеты с сайта HackageDB, а затем собрать и установить их обычным способом.

Будьте осторожны и не перекомпилируйте пакеты, от которых зависит сам GHC: это может повредить сам пакет ghc, а ghc нельзя просто перекомпилировать. Восстановить систему в этом случае можно только переустановив GHC.

5.9.7. Управление пакетами (команда ghc-pkg)

Утилита ghc-pkg предназначена для просмотра и изменения баз данных пакетов. Чтобы узнать, какие базы данных пакетов используются, выполните ghc-pkg list. Стек баз данных, о котором знает ghc-pkg, можно изменить с помощью переменной среды GHC_PACKAGE_PATH (см. Переменная среды GHC_PACKAGE_PATH), а также с помощью параметров -package-db ⟨file⟩ в командной строке ghc-pkg.

При запросе на изменение базы данных ghc-pkg по умолчанию изменяет глобальную базу данных. Параметр --user указывает работать с пользовательской базой данных, а --package-db позволяет работать с любой другой базой данных. Если указано несколько таких параметров, в качестве базы данных используется последний из них.

Команды, запрашивающие базу данных пакетов (list, latest, describe, field, dot), работают со списком баз данных, указанным флагами --user, --global и --package-db. Если ни один из этих флагов не указан, по умолчанию используется --global --user.

Если задана переменная среды GHC_PACKAGE_PATH, и её значение не заканчивается разделителем (: в Unix, ; в Windows), последняя база данных считается глобальной и по умолчанию будет изменяться командой ghc-pkg. Предполагается, что GHC_PACKAGE_PATH можно использовать для создания виртуального окружения пакетов, куда можно устанавливать пакеты Cabal, не задавая ничего, кроме GHC_PACKAGE_PATH.

Программу ghc-pkg можно запускать способами, перечисленными ниже. Если требуется указать имя пакета, его можно указать полностью, включая номер версии (например, network-1.0), либо без номера версии. Имя пакета без номера версии соответствует всем его версиям; указанное действие будет применено ко всем совпавшим пакетам. Спецификатор пакета, соответствующий всем версиям пакета, также можно записать как ⟨pkg⟩ -*, чтобы явно показать, что выбрано несколько пакетов. Чтобы сопоставлять установленный идентификатор пакета, а не только имя и версию пакета, укажите флаг --ipid.

ghc-pkg init path

Создаёт новую пустую базу данных пакетов по пути ⟨path⟩. Она не должна уже существовать.

ghc-pkg register ⟨file⟩

Считывает спецификацию пакета из файла ⟨file⟩ (вместо файла можно указать «-», чтобы использовать стандартный ввод) и добавляет её в базу данных установленных пакетов. Синтаксис ⟨file⟩ описан в разделе InstalledPackageInfo: спецификация пакета.

В спецификации должен быть указан пакет, который ещё не установлен.

ghc-pkg update ⟨file⟩

Работает так же, как register, но если пакет с таким именем уже установлен, он заменяется новым.

ghc-pkg unregister ⟨P⟩

Удаляет указанный пакет из базы данных.

ghc-pkg check

Проверяет согласованность зависимостей в базе данных пакетов и сообщает о пакетах с отсутствующими зависимостями.

ghc-pkg expose ⟨P⟩

Устанавливает флаг exposed для пакета ⟨P⟩ в значение True.

ghc-pkg hide ⟨P⟩

Устанавливает флаг exposed для пакета ⟨P⟩ в значение False.

ghc-pkg trust ⟨P⟩

Устанавливает флаг trusted для пакета ⟨P⟩ в значение True.

ghc-pkg distrust ⟨P⟩

Устанавливает флаг trusted для пакета ⟨P⟩ в значение False.

ghc-pkg list [⟨P⟩] [--simple-output]

Этот параметр отображает установленные пакеты для каждой базы данных, известной программе ghc-pkg. Сюда входят глобальная база данных, локальная база данных пользователя и все дополнительные файлы, указанные в командной строке с помощью параметра -f.

Скрытые пакеты (для которых флаг exposed имеет значение False) отображаются в списке пакетов в скобках.

Если указан необязательный идентификатор пакета ⟨P⟩, будут отображены только соответствующие ему пакеты.

Если указан параметр --simple-output, пакеты выводятся в одну строку через пробел, а имена баз данных не включаются. Это упрощает разбор вывода ghc-pkg list с помощью скрипта.

ghc-pkg find-module ⟨M⟩ [--simple-output]

Этот параметр выводит зарегистрированные пакеты, предоставляющие модуль ⟨M⟩. Примеры:

$ ghc-pkg find-module Var
c:/fptools/validate/ghc/driver/package.conf.inplace:
    (ghc-6.9.20080428)

$ ghc-pkg find-module Data.Sequence
c:/fptools/validate/ghc/driver/package.conf.inplace:
    containers-0.1

В остальных случаях он работает как ghc-pkg list, включая параметры.

ghc-pkg latest ⟨P⟩

Выводит последнюю доступную версию пакета ⟨P⟩.

ghc-pkg describe ⟨P⟩

Выводит полное описание указанного пакета. Описание имеет формат InstalledPackageInfo, такой же, как формат входного файла для ghc-pkg register. Подробности см. в разделе InstalledPackageInfo: спецификация пакета.

Если шаблону соответствуют несколько пакетов, для каждого из них выводится описание; описания разделяются строкой ---, расположенной на отдельной строке.

ghc-pkg field ⟨P⟩ ⟨field⟩[,⟨field⟩]*

Выводит только одно поле описания установленного пакета P. Можно выбрать несколько полей, разделив их запятыми.

ghc-pkg dot

Создаёт граф зависимостей пакетов в формате, подходящем для инструментов graphviz. Например, чтобы создать PDF-файл с графом зависимостей:

ghc-pkg dot | tred | dot -Tpdf >pkgs.pdf

ghc-pkg dump

Выводит полные описания всех пакетов в формате InstalledPackageInfo. Описания пакетов разделяются строкой ---, расположенной на отдельной строке.

Эта команда почти не отличается от ghc-pkg describe '*', но ghc-pkg dump предназначена для инструментов, разбирающих результаты. Например, если ghc-pkg describe '*' выдаёт ошибку, когда не находит пакетов, соответствующих шаблону, то ghc-pkg dump просто ничего не выводит.

ghc-pkg recache

Повторно создаёт файл двоичного кэша package.cache для выбранной базы данных. Это может потребоваться, если кэш по какой-либо причине перестал соответствовать содержимому базы данных (ghc-pkg предупредит вас о такой возможности).

Кроме того, ghc-pkg recache полезна при ручной регистрации пакетов: пакет можно зарегистрировать, просто поместив соответствующий файл в каталог базы данных пакетов и запустив ghc-pkg recache для обновления кэша. Такой способ регистрации пакетов может быть удобнее для систем автоматизированной сборки пакетов.

Для ⟨M⟩ в find-module, а также для ⟨P⟩ в list, describe и field поддерживается поиск по подстроке, где '*' обозначает незаданные границы подстроки (prefix*, *suffix, *infix*). Примеры (вывод опущен):

-- list all regex-related packages
ghc-pkg list '*regex*' --ignore-case
-- list all string-related packages
ghc-pkg list '*string*' --ignore-case
-- list OpenGL-related packages
ghc-pkg list '*gl*' --ignore-case
-- list packages exporting modules in the Data hierarchy
ghc-pkg find-module 'Data.*'
-- list packages exporting Monad modules
ghc-pkg find-module '*Monad*'
-- list names and maintainers for all packages
ghc-pkg field '*' name,maintainer
-- list location of haddock htmls for all packages
ghc-pkg field '*' haddock-html
-- dump the whole database
ghc-pkg describe '*'

Кроме того, ghc-pkg поддерживает следующие флаги:

-f ⟨file⟩, -package-db ⟨file⟩

Добавляет ⟨file⟩ в стек баз данных пакетов. Кроме того, ⟨file⟩ станет базой данных, изменяемой командами register, unregister, expose или hide, если это не будет переопределено более поздним параметром --package-db, --user или --global.

--force

Заставляет ghc-pkg игнорировать отсутствующие зависимости, каталоги и библиотеки при регистрации пакета и в любом случае добавлять его. Это может быть полезно, если системе установки пакетов нужно добавить пакет в GHC до сборки и установки файлов.

--global

Работает с глобальной базой данных пакетов (это значение по умолчанию). Этот флаг влияет на команды register, update, unregister, expose и hide.

--help, -?

Выводит синтаксис командной строки.

--user

Работает с локальной базой данных пакетов текущего пользователя. Этот флаг влияет на команды register, update, unregister, expose и hide.

-v [⟨n⟩], --verbose [=⟨n⟩]

Задаёт подробность вывода. Уровни подробности — от 0 до 2; по умолчанию используется уровень 1, а один параметр -v задаёт уровень 2.

-V; --version

Выводит номер версии ghc-pkg.

--ipid, --unit-id

Заставляет ghc-pkg трактовать аргументы как идентификаторы установленных модулей (например, идентификатор вида unix-2.3.1.0-de7803f1a8cd88d2161b29b083c94240). Это полезно, если указания только имени и версии пакета недостаточно для однозначного выбора (в старых версиях GHC это гарантировало уникальность, но теперь такое свойство не всегда выполняется).

5.9.8. Сборка пакета из исходного кода Haskell

Мы не рекомендуем собирать пакеты сложным способом. По возможности используйте инфраструктуру Cabal. Если ваш пакет особенно сложен или требует большого объёма настройки, возможно, придётся прибегнуть к низкоуровневым механизмам. Для тех, кто готов к этому, ниже приведено несколько советов.

При установке пакета нужно создать файл «информации об установленном пакете», который передаётся программе ghc-pkg. Содержимое этого файла описано в разделе InstalledPackageInfo: спецификация пакета.

Код Haskell в пакете можно собрать в одну или несколько архивных библиотек (например, libHSfoo.a) либо в один общий объект (например, libHSfoo.dll/.so/.dylib). Ограничение на один общий объект связано с тем, что система пакетов сообщает компилятору, когда следует выполнять вызов между общими объектами, а не внутри одного общего объекта (для вызовов между общими объектами требуется дополнительная косвенная адресация).

• Статическую библиотеку можно собрать с помощью утилиты ar следующим образом:

  ar cqs libHSfoo-1.0.a A.o B.o C.o ...
  

  где A.o, B.o и так далее — скомпилированные модули Haskell, а libHSfoo.a — создаваемая библиотека. Синтаксис может немного отличаться в вашей системе; если возникнут трудности, обратитесь к документации.

• Чтобы загрузить пакет foo, GHCi может напрямую загрузить его библиотеку libHSfoo.a, но также может загрузить пакет в виде одного предварительно скомпонованного файла HSfoo.o. Загрузка файла .o немного быстрее, но для этого требуется хранить дополнительную копию скомпилированного пакета. Как правило, если модули пакета скомпилированы с параметром -split-sections, создание HSfoo.o оправдано, поскольку ускоряет загрузку пакета в GHCi. Без -split-sections время загрузки библиотек .o и .a почти не различается, поэтому лучше сэкономить место на диске и оставить только .a. В дистрибутиве GHC для большинства пакетов, кроме самого пакета GHC, предоставляются файлы .o.

  Файл HSfoo.o автоматически создаётся Cabal; чтобы отключить его создание, используйте --disable-library-for-ghci. Для создания файла вручную можно воспользоваться следующей командой GNU ld:

  ld -r --whole-archive -o HSfoo.o libHSfoo.a
  

  (замените --whole-archive на -all_load в MacOS X)

• При сборке пакета в виде общей библиотеки для выполнения этапа компоновки можно использовать GHC. Это позволяет скрыть некоторые детали работы нижележащего компоновщика и предоставляет единый интерфейс для всех вариантов общих объектов, поддерживаемых GHC (DLL, ELF DSO и dylib в Mac OS). Общий объект должен иметь имя особого формата по двум причинам: (1) имя должно содержать версию компилятора GHC, чтобы варианты библиотек, собранные разными версиями GHC и, вероятно, несовместимые по соглашениям о вызовах, не конфликтовали; (2) оно должно отличаться от имени статической библиотеки, иначе нельзя будет достаточно точно управлять компоновщиком, чтобы работали флаги -static/-dynamic; см. раздел Параметры, влияющие на компоновку.

  ghc -shared -dynamic -o libHSfoo-1.0-ghcGHCVersion.so A.o B.o C.o
  

  Использование номера версии GHC в имени общего объекта позволяет устанавливать варианты библиотек, собранные разными версиями GHC, в стандартные системные каталоги, например в Unix-подобных системах — в /usr/lib. Чтобы узнать номер версии GHC, выполните ghc --numeric-version и используйте полученный результат вместо ⟨GHCVersion⟩. См. также раздел Параметры, влияющие на генерацию кода, где описана подготовка объектных файлов к компоновке в общий объект.

• При сборке общей библиотеки необходимо следить за тем, чтобы результирующий объект получил подходящее имя. В частности, GHC ожидает, что имя общего объекта будет иметь формат libHS<unit id>-ghc<ghc version>.<ext>, где unit id — идентификатор модуля, указанный при компиляции с помощью флага -this-unit-id ⟨unit-id⟩, ghc version — версия GHC, создавшей/использующей объект, а ext — обычное расширение файлов общих объектов в целевой системе.

Чтобы скомпилировать модуль, который будет частью нового пакета, используйте параметры -package-name (для указания имени пакета) и -library-name (для указания версии и хешей версий его идентификаторов) (Использование пакетов). Если не указать эти параметры при компиляции пакета, это, вероятно, приведёт к проблемам, которые обнаружатся позднее при попытке импортировать модули из пакета. В этот момент GHC сообщит, что ожидаемое имя пакета, из которого должен происходить модуль, не совпадает с именем пакета, сохранённым в файле .hi.

При сборке каждого пакета в виде одного файла общего объекта ссылки внутри пакета обходятся дешевле ссылок между пакетами, поскольку ссылка на общий объект требует дополнительной косвенной адресации. Разумеется, это относится и к пакету main.

5.9.9. InstalledPackageInfo: спецификация пакета

Спецификация пакета представляет собой запись Haskell; в частности, это запись Distribution.InstalledPackageInfo.InstalledPackageInfo из модуля Distribution.InstalledPackageInfo, входящего в пакет Cabal, распространяемый вместе с GHC.

У InstalledPackageInfo есть синтаксис, удобный для чтения и записи человеком. Функции parseInstalledPackageInfo и showInstalledPackageInfo соответственно читают и записывают данные в этом формате. Вот пример InstalledPackageInfo для пакета unix:

$ ghc-pkg describe unix
name: unix
version: 2.3.1.0
id: unix-2.3.1.0-de7803f1a8cd88d2161b29b083c94240
license: BSD3
copyright:
maintainer: libraries@haskell.org
stability:
homepage:
package-url:
description: This package gives you access to the set of operating system
             services standardised by POSIX 1003.1b (or the IEEE Portable
             Operating System Interface for Computing Environments -
             IEEE Std. 1003.1).
             .
             The package is not supported under Windows (except under Cygwin).
category: System
author:
exposed: True
exposed-modules: System.Posix System.Posix.DynamicLinker.Module
                 System.Posix.DynamicLinker.Prim System.Posix.Directory
                 System.Posix.DynamicLinker System.Posix.Env System.Posix.Error
                 System.Posix.Files System.Posix.IO System.Posix.Process
                 System.Posix.Process.Internals System.Posix.Resource
                 System.Posix.Temp System.Posix.Terminal System.Posix.Time
                 System.Posix.Unistd System.Posix.User System.Posix.Signals
                 System.Posix.Signals.Exts System.Posix.Semaphore
                 System.Posix.SharedMem
hidden-modules:
trusted: False
import-dirs: /usr/lib/ghc-6.12.1/unix-2.3.1.0
library-dirs: /usr/lib/ghc-6.12.1/unix-2.3.1.0
hs-libraries: HSunix-2.3.1.0
extra-libraries: rt util dl
extra-ghci-libraries:
include-dirs: /usr/lib/ghc-6.12.1/unix-2.3.1.0/include
includes: HsUnix.h execvpe.h
depends: base-4.2.0.0-247bb20cde37c3ef4093ee124e04bc1c
hugs-options:
cc-options:
ld-options:
framework-dirs:
frameworks:
haddock-interfaces: /usr/share/doc/ghc/html/libraries/unix/unix.haddock
haddock-html: /usr/share/doc/ghc/html/libraries/unix

Ниже приведено краткое описание синтаксиса этого файла:

Описание пакета состоит из нескольких пар «поле/значение». Поле начинается с имени в левом столбце, за которым следует «:»; значение продолжается до следующей строки, начинающейся в левом столбце, или до конца файла.

Синтаксис значения зависит от поля. Существуют следующие типы полей:

произвольный текст

Любая строка; интерпретация и разбор не выполняются.

строка

Последовательность символов без пробелов или произвольная последовательность символов в кавычках "....".

список строк

Последовательность строк, разделённых запятыми. Последовательность может быть пустой.

Кроме того, некоторые поля имеют особый синтаксис (например, имена пакетов, версии и зависимости).

Допустимые поля и их типы:

name

(строка) Имя пакета (без версии).

id

(строка) Идентификатор установленного пакета. Подходящий идентификатор можно выбрать самостоятельно.

version

(строка) Версия пакета, обычно в формате A.B (допускается любое количество компонентов).

license

(строка) Тип лицензии, на условиях которой распространяется пакет. Значение этого поля относится к типу Distribution.License.License.

license-file

(необязательная строка) Имя файла с подробной информацией о лицензии этого пакета.

copyright

(необязательный произвольный текст) Строка с информацией об авторских правах.

maintainer

(необязательный произвольный текст) Адрес электронной почты сопровождающего пакет.

stability

(необязательный произвольный текст) Строка, описывающая стабильность пакета (например, стабильный, предварительный или экспериментальный).

homepage

(необязательный произвольный текст) URL домашней страницы пакета.

package-url

(необязательный произвольный текст) URL загружаемого дистрибутива этого пакета. Дистрибутив должен быть пакетом Cabal.

description

(необязательный произвольный текст) Описание пакета.

category

(необязательный произвольный текст) Категория, к которой относится пакет. Это поле предназначено для использования в будущем централизованном механизме распространения пакетов, предварительно названном Hackage.

author

(необязательный произвольный текст) Автор пакета.

exposed

(логическое значение) Доступен ли пакет.

exposed-modules

(список строк) Модули, доступные в этом пакете.

hidden-modules

(список строк) Модули, предоставляемые этим пакетом, но недоступные программисту. Эти модули нельзя импортировать, однако на них распространяется ограничение на перекрытие: ни один другой пакет в той же программе не может предоставлять модуль с таким же именем.

reexported-modules

Модули, повторно экспортируемые этим пакетом. Список имеет формат pkg:OldName as NewName (A@orig-pkg-0.1-HASH): первая часть строки содержит спецификацию повторного экспорта, заданную пользователем (возможно, без квалификатора пакета и переименования), а в скобках указан исходный пакет, который предоставлял модуль под определённым именем. Для повторно экспортируемых модулей действует более мягкое ограничение на перекрытие: двум пакетам разрешено повторно экспортировать один и тот же модуль под одним именем, если повторно экспортируемый модуль идентичен.

trusted

(логическое значение) Является ли пакет доверенным.

import-dirs

(список строк) Список каталогов с файлами интерфейсов (файлами .hi) этого пакета.

Если пакет содержит библиотеки для профилирования, файлы интерфейсов соответствующих модулей библиотеки должны иметь суффикс .p_hi. Это позволяет пакету содержать обычные версии библиотек и версии для профилирования без конфликтов (см. также library_dirs ниже).

library-dirs

(список строк) Список каталогов с библиотеками этого пакета.

hs-libraries

(список строк) Список библиотек с кодом Haskell для этого пакета без суффикса .a или .dll. При сборке пакетов в виде библиотек также опускается префикс lib.

Для использования с GHCi каждой библиотеке также нужен объектный файл. Имя объектного файла не имеет префикса lib и заканчивается обычным для вашей платформы суффиксом объектного файла.

Например, если в спецификации пакета библиотека Haskell указана как HSfoo, разные варианты библиотеки, используемые GHC, будут называться так:

libHSfoo.a

Имя библиотеки в системах Unix и Windows (mingw).

HSfoo.dll

Имя динамической библиотеки в системах Windows (необязательно).

HSfoo.o; HSfoo.obj

Объектный вариант библиотеки, используемый GHCi.

extra-libraries

(список строк) Список дополнительных библиотек для этого пакета. Разница между hs-libraries и extra-libraries состоит в том, что у hs-libraries обычно есть несколько версий для поддержки профилирования, параллельной обработки и других параметров сборки. Чтобы различать эти версии, им присваиваются разные суффиксы. Например, версия стандартной библиотеки прелюдии для профилирования называется libHSbase_p.a, где _p обозначает версию для профилирования. GHC автоматически добавляет суффикс только для hs-libraries; для библиотек в extra-libraries суффикс не добавляется.

Библиотеки, перечисленные в extra-libraries, могут быть любыми библиотеками, поддерживаемыми компоновщиком вашей системы, включая динамические библиотеки (.so в Unix, .DLL в Windows).

Кроме того, extra-libraries помещаются в командную строку компоновщика после hs-libraries для того же пакета. Если зависимости вашего пакета направлены в другую сторону (то есть extra-libraries зависит от hs-libraries), а библиотеки являются статическими, возможно, потребуется создать два отдельных пакета.

include-dirs

(список строк) Список каталогов с подключаемыми файлами C для этого пакета.

includes

(список строк) Список файлов, подключаемых при компиляции через C с использованием этого пакета. Обычно в подключаемых файлах содержатся прототипы функций C, используемых в пакете, на случай, если они будут вызваны в результате встраивания функций Haskell из пакета.

depends

(список идентификаторов пакетов) Пакеты, от которых зависит этот пакет.

hugs-options

(список строк) Параметры, передаваемые Hugs для этого пакета.

cc-options

(список строк) Дополнительные аргументы, добавляемые в командную строку gcc при использовании этого пакета (только для компиляции через C).

ld-options

(список строк) Дополнительные аргументы, добавляемые в командную строку gcc (для компоновки) при использовании этого пакета.

framework-dirs

(список строк) В Darwin/MacOS X — список каталогов с фреймворками для этого пакета. Соответствует параметру -framework-path. На остальных платформах игнорируется.

frameworks

(список строк) В Darwin/MacOS X — список фреймворков для компоновки. Соответствует параметру -framework. Чтобы узнать, что такое фреймворки, обратитесь к документации разработчика Apple. На остальных платформах эта запись игнорируется.

haddock-interfaces

(список строк) Список имён файлов с файлами интерфейсов Haddock (файлами .haddock) для этого пакета.

haddock-html

(необязательная строка) Каталог с HTML-файлами этого пакета, созданными Haddock.

5.9.10. Компоновка с библиотеками C++

Для использования библиотек C++ требуется компоновка с системной стандартной библиотекой C++ целевой платформы. Поскольку необходимые для этого настройки сильно зависят от платформы, GHC предоставляет встроенный пакет system-cxx-std-lib. В этом пакете собраны необходимые для компоновки со стандартной библиотекой C++ настройки. Его можно использовать с флагом -package ⟨pkg⟩ или полем Cabal build-depends, чтобы компоновать код со стандартной библиотекой C++.