Package: agda-pkg
Agda-pkgis a tool to manageAgdalibraries with extra features like
installing libraries from different kind of sources.This tool does not modifyAgdaat all, it just manages systematically the directory.agdawith.agda/defaultsand.agda/librariesfiles used by
Agda to locate the available libraries. For more information about how Agda package
system works, please read the official documentationhere.Quick StartThe most common usages of agda-pkg are the following:To installAgda-pkgjust run the following command:$pip3installagda-pkgTo install your library, go to the root directory of your source code and run:$apkginstall--editable.To install a library fromagda/package-index.$apkginit
$apkginstallstandard-libraryA list of the available packages is shown below.To install aGithub repositorywith aspecific version release:$apkginstall--githubagda/agda-stdlib--versionv1.3To install a library from a Github repository with aspecific branchwith aspecific library name:$apkginstall--githubplfa/plfa.github.io--branchdev--nameplfaIndexed librariesLibrary nameLatest versionURLagda-basev0.2https://github.com/pcapriotti/agda-base.gitagda-categoriesv0.1https://github.com/agda/agda-categories.gitagda-metisv0.2.1https://github.com/jonaprieto/agda-metis.gitagda-preludedf679cfhttps://github.com/UlfNorell/agda-prelude.gitagda-propv0.1.2https://github.com/jonaprieto/agda-prop.gitagda-reale1558b62https://gitlab.com/pbruin/agda-real.gitagda-ring-solverd1ed21chttps://github.com/oisdk/agda-ring-solver.gitagdarsecv0.3.0https://github.com/gallais/agdarsec.gitalga-theory0fdb96chttps://github.com/algebraic-graphs/agda.gitatacaa9a7c06https://github.com/jespercockx/ataca.gitcatv1.6.0https://github.com/fredefox/cat.gitcubicalv0.1https://github.com/agda/cubical.gitFiniteSetsc8c2600https://github.com/L-TChen/FiniteSets.gitfotcapia-1.0.2https://github.com/asr/fotc.gitgenericf448ab3https://github.com/effectfully/Generic.githott-core1037d82https://github.com/HoTT/HoTT-Agda.githott-theorems1037d82https://github.com/HoTT/HoTT-Agda.gitHoTT-UF-Agda9d0f38ehttps://github.com/martinescardo/HoTT-UF-Agda-Lecture-Notes.gitialv1.5.0https://github.com/cedille/ial.gitlightweight-preludeb2d440ahttps://github.com/L-TChen/agda-lightweight-prelude.gitmini-hottd9b4a7bhttps://github.com/jonaprieto/mini-hott.gitMtacAR5417230https://github.com/L-TChen/MtacAR.gitplfastable-web-2019.09https://github.com/plfa/plfa.github.io.gitrouting-librarythesishttps://github.com/MatthewDaggitt/agda-routing.gitstandard-libraryv1.3https://github.com/agda/agda-stdlib.gitUsage manualInitialisation of the package indexThe easiest way to install libraries is by usingthe package index.agda-pkguses a local database to maintain a register of all
libraries available in your system. To initialize the index and the
database please run the following command:$apkginit
Indexinglibrariesfromhttps://github.com/agda/package-index.gitNote. To use a different location for your agda filesdefaultsandlibraries, you can set up the environment variableAGDA_DIRbefore runapkgas follows:$exportAGDA_DIR=$HOME/.agdaOther way is to create a directory.agdain your directory and runagda-pkgfrom that directory.agda-pkgwill prioritize the.agdadirectory in the current directory.Help commandCheck all the options of a command or subcommand by using the flag--help.$apkg--help
$apkginstall--helpUpgrade the package indexRecall updating the index every once in a while usingupgrade.$apkgupgrade
UpdatingAgda-Pkgfromhttps://github.com/agda/package-index.gitIf you want to index your library go tothe package indexand makePR.Environmental variablesIf there is an issue with your installation or you suspect something
is going wrong. You might want to see the environmental variables used by apkg.$apkgenvironmentList all the packages availableTo see all the packages available run the following command:$apkglistThis command also has the flag--fullto display a version of the
this list with more details.Installation of packagesInstall a library is now easy. We have multiple ways to install a package.from thepackage-index$ apkg install standard-libraryfrom alocal directory$apkginstall.or even much simpler:$apkginstallInstalling a library creates a copy for agda in the directory assigned
by agda-pkg. If you want your current directory to be taken into
account for any changes use the--editableoption.  as shown below.$apkginstall--editable.from a github repository$apkginstall--githubagda/agda-stdlib--versionv1.1from a git repository$apkginstallhttp://github.com/jonaprieto/agda-prop.gitTo specify the version of a library, we use the flag--version$apkginstallstandard-library--versionv1.0Or simpler by using@or==as it follows.$apkginstallstandard-library@v1.0
$apkginstallstandard-library==v1.0Multiple packages at onceTo install multiple libraries at once, we have two options:Using the inline method$apkginstallstandard-libraryagda-baseUse@or==if you need a specific version, see above
examples.Using a requirement file:Generate a requirement file usingapkg freeze:$apkgfreeze>requirements.txt
$catrequirements.txt
standard-library==v1.1Now, use the flag-rto install all the listed libraries
in this file:$apkginstall-rrequirements.txtCheck all the options of this command with the help information:$apkginstall--helpUninstalling a packageUninstalling a package will remove the library from the visible libraries for Agda.using the name of the library$apkguninstallstandard-libraryinfering the library name from the current directory$apkguninstall.And if we want to remove the library completely (the sources and
everything), we use the flag--remove-cache.$apkguninstallstandard-library--remove-cacheUpdate a package to latest versionWe can get the latest version of a package from
the versions registered in the package-index.Update all the installed libraries:$apkgupdateUpdate a specific list of libraries. If some
library is not installed, this command will installed
the latest version of it.$apkgupdatestandard-libraryagdarsecSee packages installed$apkgfreeze
standard-library==v1.1This command is useful to keep in a file the versions used for your project
to install them later.$apkgfreeze>requirements.txtTo install from this requirement file run this command.$apkginstall<requirements.txtApproximate search of packagesWe make a search (approximate) by using keywords and title of the
packages from the index. To perform such a search, see the following
example:$apkgsearchmetis1resultin0.0012656739999998834seg
cubical
url:https://github.com/agda/cubical.git
installed:FalseGet all the information of a package$apkginfocubicalCreating a library for Agda-PkgIn this section, we describe how to build a library.To build a project usingagda-pkg, we just run the following command:$apkgcreateSome questions are going to be prompted in order to create
the necessary files for Agda and for Agda-Pkg.The output is a folder like the following showed below.Directory structure of an agda libraryA 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$ cat mylibrary.agda-libname:mylibrary  -- Commentdepend:LIB1 LIB2LIB3LIB4include:PATH1PATH2PATH3.agda-pkg library fileThis file only works foragda-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.$ cat mylibrary.agda-pkgname:mylibraryversion:v0.0.1author:-AuthorName1-AuthorName2category:cat1, cat2, cat3homepage:http://github.com/user/mylibrarylicense:MITlicense-file:LICENSE.mdsource-repository:http://github.com/user/mylibrary.gittested-with:2.6.0description:Put here a description.include:-PATH1-PATH2-PATH3depend:-LIB1-LIB2-LIB3-LIB4Using with Nix or NixOSAnix-shellenvironment that loadsagda-pkgas well asagdaandagda-modefor Emacs is available. To use this,apkgcan put the necessary
files in your project folder by running one of the following commands:$curl-Lhttps://gist.github.com/jonaprieto/53e55263405ee48a831d700f27843931/download|tar-xvz--strip-components=1or if you already have installed agda-pkg:$apkgnixosThen, you will have the following files:./hello-world.agda
./agda_requirements.txt
./shell.nix
./deps.nix
./emacs.nixFrom where you can run the nix shell.$nix-shellTo launch Emacs withagda-modeenabled, runmymacsin the newly launched
shell;mymacswill also load your~/.emacsfile if it exists. If you are
usingSpacemacs, you will need to editshell.nixto use~/.spacemacsinstead.The files provided by the commands above are also available in this repository
(apkg/support/nix) and in a third-partyexample
repositoryto give an idea of exactly
which files need to be copied to your project.Example:$cathello-world.agdamodulehello-worldwhereopenimportIOmain=run(putStrLn"Hello, World!")Runmymacs hello-world.agdathen typeC-c C-x C-cin emacs to compile the loaded hello world file.ConfigurationEdit any of thenixexpressions as needed. In particular:To add Agda dependencies viaagda-pkg, editagda_requirements.txtTo add more 4Haskell or other system dependencies or other
target-language dependencies, editdeps.nix.To add or alter the editor used, change themyEmacsreferences inshell.nixor add similar derivations.Optionally, create.emacs_user_configin the repository root directory and
add any additional config, such as(setq agda2-backend "GHC")to use GHC by
default when compiling Agda files from emacs.AboutThis is a proof of concept of an Agda Package Manager.
Contributions are always welcomed.