posix-api.cabal

cabal-version:      3.0
name:               posix-api
version:            0.7.2.0
synopsis:           posix bindings
description:
  This library provides a very thin wrapper around POSIX APIs. It can be
  compiled on any operating system that implements the standard as specified
  in <http://pubs.opengroup.org/onlinepubs/9699919799/ IEEE Std 1003.1>
  faithfully. It has similar goals as the `unix` package, but its design
  differs in several areas:
  .
  * `ByteArray` and `Addr` are used pervasively. There is no use of
  `String` in this library.
  .
  * Functions do not throw errors. This library uses `IO (Either Errno a)`
  in places where `unix` would use `IO a`.
  .
  * The numeric types from `Foreign.C.Types` and `System.Posix.Types` are
  used in the type signatures of functions so that a haskell function's
  type signature matches its underlying POSIX equivalent exactly.
  .
  * Flags are newtypes over `CInt` (or whatever integral type matches the
  posix specification) rather than enumerations. The data constructors
  are exported, making the types extensible for operating system that
  have additional flags.
  .
  About a dozen other packages offers wrappers for some subset of the POSIX
  specification are strewn across hackage. They include `regex-posix`,
  `posix-paths`, `posix-timer`, `posix-socket`, `posix-filelock`,
  `posix-acl`, etc. This library differs from all off these in various
  ways. Here are some of the design guidelines followed here that distinguish
  this package from some or all of these others:
  .
  * Scope. Although this library does not include all APIs specified by
  POSIX, it welcomes as many of them as anyone is willing to implement.
  .
  * Monomorphization. Effectful functions in this library return their
  results in `IO` rather than using a type that involves `MonadIO`
  or `MonadBaseControl`.
  .
  * Typeclass avoidance. This library does not introduce new typeclasses.
  Overloading is eschewed in favor of providing multiple functions
  with distinct names.
  .
  * Minimality. Functions wrapping the POSIX APIs do little more than
  wrap the underlying functions. The major deviation here is that,
  when applicable, the wrappers allocate buffers are the underlying
  functions fill. This eschews C's characteristic buffer-passing
  in favor of the Haskell convention of allocating internally and returning.
  A more minor deviation is that for safe FFI calls, this library
  will perform additional work to ensure that only pinned byte arrays are
  handed over.
  .
  Unlike `network`, this sockets API in this library does not integrate
  sockets with GHC's event manager. This is geared
  toward an audience that understands how to use `threadWaitRead`
  and `threadWaitWrite` with unsafe FFI calls to avoid blocking
  the runtime.

homepage:           https://github.com/byteverse/posix-api
bug-reports:        https://github.com/byteverse/posix-api/issues
license:            BSD-3-Clause
license-file:       LICENSE
author:             Andrew Martin
maintainer:         amartin@layer3com.com
copyright:          2018 Andrew Martin
category:           System
build-type:         Simple
extra-source-files:
  cbits/HaskellPosix.c
  include/custom.h
  include/HaskellPosix.h

extra-doc-files:
  CHANGELOG.md
  README.md

tested-with:        GHC ==9.4.8 || ==9.6.3 || ==9.8.1

flag assertions
  manual:      True
  description: Extra run-time invariant checking
  default:     False

common build-settings
  default-language: Haskell2010
  ghc-options:      -Wall -Wunused-packages

library
  import:             build-settings
  exposed-modules:
    Foreign.C.String.Managed
    Linux.Epoll
    Linux.MessageQueue
    Linux.Socket
    Posix.Directory
    Posix.File
    Posix.MessageQueue
    Posix.Poll
    Posix.Select
    Posix.Socket
    Posix.Struct.AddressInfo.Peek
    Posix.Struct.AddressInfo.Poke
    Posix.Struct.SocketAddressInternet.Peek
    Posix.Types

  other-modules:
    Assertion
    Linux.Epoll.Types
    Linux.MessageQueue.Types
    Linux.Socket.Types
    Posix.File.Types
    Posix.MessageQueue.Types
    Posix.Poll.Types
    Posix.Socket.Platform
    Posix.Socket.Types

  build-depends:
    , base              >=4.16.3 && <5
    , byte-order        >=0.1.2  && <0.2
    , byteslice         >=0.2.10 && <0.3
    , primitive         >=0.9    && <0.10
    , primitive-addr    >=0.1    && <0.2
    , primitive-offset  >=0.2    && <0.3
    , run-st            >=0.1.1  && <0.2
    , text-short        >=0.1.5

  hs-source-dirs:     src

  if flag(assertions)
    hs-source-dirs: src-assertions

  else
    hs-source-dirs: src-noassertions

  if os(linux)
    hs-source-dirs: src-linux

  ghc-options:        -O2
  c-sources:          cbits/HaskellPosix.c
  include-dirs:       include
  includes:           HaskellPosix.h
  build-tool-depends: hsc2hs:hsc2hs >=0.68.5

test-suite test
  import:         build-settings
  type:           exitcode-stdio-1.0
  hs-source-dirs: test
  main-is:        Main.hs
  build-depends:
    , base
    , posix-api
    , primitive    >=0.7
    , tasty
    , tasty-hunit

  ghc-options:    -threaded

source-repository head
  type:     git
  location: git://github.com/byteverse/posix-api.git