Metadata-Version: 2.1
Name: agda-pkg
Version: 0.1.17
Summary: The Agda Package Manager
Home-page: https://github.com/apkgbot/agda-pkg
Author: Jonathan Prieto-Cubides & Camilo Rodriguez
Author-email: jcu043@uib.no
License: MIT
Keywords: agda,package-manager,agda-pkg
Platform: any
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3.6
Requires-Python: >=3.6.0
Description-Content-Type: text/markdown
Requires-Dist: click
Requires-Dist: gitpython
Requires-Dist: pyyaml
Requires-Dist: pony
Requires-Dist: whoosh
Requires-Dist: ponywhoosh
Requires-Dist: natsort
Requires-Dist: click-log
Requires-Dist: requests
Requires-Dist: humanize

agda-pkg [![PyPI version](https://badge.fury.io/py/agda-pkg.svg)](https://badge.fury.io/py/agda-pkg) [![Build Status](https://travis-ci.org/apkgbot/agda-pkg.svg?branch=master)](https://travis-ci.org/apkgbot/agda-pkg)
========

The Agda package manager that we all have been waiting for. This
tool do not modify `Agda` at all, it will just manage systematically the directory
`.agda` and its files: `.agda/defaults` and `.agda/libraries`.

<img src="https://github.com/apkgbot/agda-pkg/raw/master/assets/demo.gif"
 alt="agda package manager installation" height=500 align="right" />

**Table of contents**

<!-- TOC depthFrom:1 depthTo:6 withLinks:1 updateOnSave:1 orderedList:0 -->

- [Quick Start](#quick-start)
- [Usage](#usage)
    - [Initialisation of the package index](#initialisation-of-the-package-index)
    - [Help command](#help-command)
    - [Upgrade package indexed](#upgrade-package-indexed)
    - [List all the packages available](#list-all-the-packages-available)
    - [Installation of packages](#installation-of-packages)
    - [Uninstalling a package](#uninstalling-a-package)
    - [See packages installed](#see-packages-installed)
    - [Approximate search of packages](#approximate-search-of-packages)
    - [Get all the information of a package](#get-all-the-information-of-a-package)
- [Managing your own library](#managing-your-own-library)
    - [Directory structure of an agda library](#directory-structure-of-an-agda-library)
    - [.agda-lib library file](#agda-lib-library-file)
    - [.agda-pkg library file](#agda-pkg-library-file)

<!-- /TOC -->

# Quick Start

To install `agda-pkg`, you must have installed `Python 3.6+` or a latter version
on your machine. In addition, the python package manager `pip 18.0+`.

We have tested `agda-pkg` with `Agda v2.5.4+`.

Installing using `pip`:

```
    $ pip install agda-pkg
```

Now, we can run the package manager using the command `agda-pkg` or even
shorter just `apkg`.

# Usage

## Initialisation of the package index

The easiest way to get libraries is from [the package index].
We will use this index to download and to install
Agda libraries. In addition, `agda-pkg` use a database to
maintain a register of all libraries available. To initialise
the index and the database run the following command:

```
    $ apkg init
    Indexing libraries from https://github.com/apkgbot/package-index.git
```

## Help command

```
    $ apkg --help
```

## Upgrade package indexed

Recall updating the index every once in a while

```
    $ apkg upgrade
    Updating Agda-Pkg from https://github.com/apkgbot/package-index.git
```

If you want to index your library make a [PR] in [the package index]

## List all the packages available

To see all the package available run the following command:

```
    $ apkg list
```

This command also has the flag `--short` to display a short version of the
same list.

## Installation of packages

We have three possibilities to install a package:


<img src="https://github.com/apkgbot/agda-pkg/raw/master/assets/index-stdlib.gif"
 alt="agda package manager installation" width=350 align="right" />

 -   from the [package index](http://github.com/apkgbot/package-index)

 ```
     $ apkg install standard-library
 ```

-   from a [local directory]

```
    $ apkg install .
```

-   from a github repository

```
    $ apkg install --github agda/agda-stdlib --version v0.16
```

-   from a git repository

```
    $ apkg install http://github.com/jonaprieto/agda-prop.git
```


### Installation of multiple packages at once


We may want to install multiple libraries at once,
so we have two options:

1. Using the inline method

```
    $ apkg install standard-library agda-prop agda-metis
```

2. Using a requirement file:

Generate a requirement file using `apkg freeze`:

```
    $ apkg freeze > requirements.txt
    $ cat requirements.txt
    agda-metis==0.1
    agda-prop==0.1.1
````

Now, use the flag `-r` to install all the listed libraries
in this file:

```
    $ apkg install -r requirements.txt
```


Lastly, to see all the options, pleasee check out the help information:

```
    $ apkg install --help
```

## Uninstalling a package

Uninstall a package by default, just hide the library for Agda but no
remove the sources:

```
    $ apkg uninstall standard-library
```

If you want to remove completely the source and everything, use
remove-cache flag.

```
    $ apkg uninstall standard-library --remove-cache
```

## See packages installed


```
    $ apkg freeze
```

Useful to save the versions used for each library:


```
    $ apkg freeze > requirements.txt
```

You may want to install from the requirements file:


```
    $ apkg install < requirements.txt
```

## Approximate search of packages

We make a search (approximate) by using keywords and title of the
packages in the index. To perform such a search, see the following
example:


```
    $ apkg search metis
    1 result in 0.0026731969992397353seg
    matches: {'name': [b'agda-metis']}

    agda-metis
    ==========
    url: https://github.com/jonaprieto/test-agdapkgbot.git
```

## Get all the information of a package


```
    $ apkg info agda-prop
    library: agda-prop
    sha: 6b2ea8e099ac6968004ec57d96f19b46bcb081ff
```

# Managing your own library

## Directory structure of an agda library

A common Agda library has the following structure:

```
$ tree -L 1 mylibrary/
mylibrary/
├── LICENSE
├── README.md
├── mylibrary.agda-lib
├── mylibrary.agda-pkg
├── src
└── test

2 directories, 3 files
```

## .agda-lib library file

```yaml
$ cat mylibrary.agda-lib
name: mylibrary  -- Comment
depend: LIB1 LIB2
  LIB3
  LIB4
include: PATH1
  PATH2
  PATH3
```

## .agda-pkg library file

This file only works for `agda-pkg`. The idea of
this file is to provide more information about the
package, pretty similar to the cabal files in Haskell.
This file has priority over its version `.agda-lib`.

```yaml
$ cat mylibrary.agda-pkg
name:              mylibrary
version:           0.0.1
author:            AuthorName
category:          [ classic, logic, theorems ]
homepage:          http://github.com/user/mylibrary
license:           MIT
license-file:      LICENSE.md
source-repository: http://github.com/user/mylibrary.git
tested-with:       2.5.6
description:       Put here a description.

include:
    - PATH1
    - PATH2
    - PATH3
depend:
    - LIB1
    - LIB2
    - LIB3
    - LIB4

```

  [the package index]: https://github.com/apkgbot/package-index
  [local directory]: https://agda.readthedocs.io/en/v2.5.4/tools/package-system.html
  [PR]: https://github.com/apkgbot/package-index/pull/new/master

# About

This is the `Python` version for the Agda Package Manager.
The Haskell version is an [early stage](http://github.com/jonaprieto/agda-pkg),
we more spare time, I hope to finish that version.

Any contribution or feedback to improve this work is very welcomed.

