squibid/dep
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Create readme and add license

Browse Source
This commit is contained in:
phosphene47
2021-11-17 21:16:50 +11:00
parent b516ae1e9e
commit ecb95923c4
2 changed files with 425 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

21
LICENSE Normal file
View File

@ -0,0 +1,21 @@
MIT License
Copyright (c) 2021 chiya.dev
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.

404
README.md Normal file
View File

@ -0,0 +1,404 @@
# dep
> This readme is a work in progress.
A versatile, declarative and correct
[neovim](https://neovim.io/) package manager in [lua](https://www.lua.org/).
Written for personal use by [phosphene47](https://github.com/phosphene47).
What does that mean?
1. `versatile` - packages can be declared in any lua file in any order of your liking.
2. `declarative` - packages are declared using simple lua tables.
3. `correct` - packages are always loaded in a correct and consistent order.
## Requirements
- [neovim](https://neovim.io/) 0.5+
- [git](https://git-scm.com/)
## Setup
1. Create `lua/bootstrap.lua` in your neovim config directory.
```lua
-- ~/.config/nvim/lua/bootstrap.lua:
-- automatically install `chiyadev/dep` on startup
local path = vim.fn.stdpath("data") .. "/site/pack/deps/opt/dep"
if vim.fn.empty(vim.fn.glob(path)) > 0 then
vim.fn.system({ "git", "clone", "--depth=1", "https://github.com/chiyadev/dep", path })
end
vim.cmd("packadd dep")
```
2. In `init.lua`, call `dep` with an array of package specifications.
```lua
require "bootstrap"
require "dep" {
-- list of package specs...
}
```
## Commands
- `:DepSync` - installs new packages, updates packages to the latest versions,
cleans removed packages and reloads packages as necessary.
- `:DepClean` - cleans removed packages.
- `:DepReload` - reloads all packages.
- `:DepList` - prints the package list, performance metrics and dependency graphs.
- `:DepLog` - opens the log file.
- `:DepConfig` - opens the file that called dep, for convenience.
## Package specification
A package must be declared in the following format.
```lua
{
-- [string] Specifies the full name of the package.
-- This is the only required field; all other fields are optional.
"user/package",
-- [function] Code to run after the package is loaded into neovim.
function()
require "package".setup(...)
end,
-- [function] Code to run before the package is loaded into neovim.
setup = function()
vim.g.package_config = ...
end,
-- [function] Code to run after the package is installed or updated.
config = function()
os.execute(...)
end,
-- [string] Overrides the short name of the package.
-- Defaults to a substring of the full name after '/'.
as = "custom_package",
-- [string] Overrides the URL of the git repository to clone.
-- Defaults to "https://github.com/{full_name}.git".
url = "https://git.chiya.dev/user/package.git",
-- [string] Overrides the name of the branch to clone.
-- Defaults to whatever the remote configured as their HEAD, which is usually "master".
branch = "develop",
-- [boolean] Prevents the package from being loaded.
disable = true,
-- [boolean] Prevents the package from being updated.
pin = true,
-- [string|array] Specifies dependencies that must be loaded before the package.
-- If given a string, it is wrapped into an array.
requires = {...},
-- [string|array] Specifies dependents that must be loaded after the package.
-- If given a string, it is wrapped into an array.
deps = {...}
}
```
When a string is given where a package specification table is expected,
it is assumed to be the package's full name.
```lua
require "dep" {
-- these two are equivalent
"user/package",
{ "user/package" },
}
```
A package can be declared multiple times. Multiple declarations of the same package are
combined into one. This is useful when declaring dependencies, which is explored later.
```lua
require "dep" {
{
"user/package",
requires = "user/dependency",
disabled = true,
config = function()
print "my config hook"
end
},
{
"user/package",
requires = "user/another_dependency",
deps = "user/dependent",
disabled = false,
config = function()
os.execute("make")
end
}
}
-- the above is equivalent to
require "dep" {
{
"user/package",
requires = { "user/dependency", "user/another_dependency" },
deps = "user/dependent",
disabled = true,
config = function()
print "my config hook"
os.execute("make")
end
}
}
```
## Declaring dependencies
The dependencies and dependents declared in a package specification are themselves
package specifications. If a dependency or dependent is declared multiple times,
they are combined into one just like normal package specifications.
```lua
require "dep" {
{
"user/package",
requires = {
{
"user/dependency1",
requires = "user/dependency2"
}
}
}
}
-- the above is equivalent to
require "dep" {
{
"user/dependency2",
deps = {
{
"user/dependency1",
deps = "user/package"
}
}
}
}
-- which is equivalent to
require "dep" {
{
"user/dependency1",
requires = "user/dependency2",
deps = "user/package"
}
}
-- which is equivalent to
require "dep" {
{
"user/dependency1",
requires = "user/dependency2"
},
{
"user/package",
requires = "user/dependency1"
}
}
-- which is equivalent to
require "dep" {
{
"user/dependency2",
deps = "user/dependency1"
},
{
"user/dependency1",
deps = "user/package"
}
}
-- all of the above are guaranteed to load in the following order: dependency2, dependency1, package
```
If dep detects a circular dependency cycle, it reports the problematic packages
instead of hanging or crashing.
```lua
-- this throws an error saying package1 depends on package2 which depends on package1
require "dep" {
{
"user/package1",
requires = "user/package2"
},
{
"user/package2",
requires = "user/package1"
}
}
```
A dependency can be marked as disabled, which disables all dependents automatically.
```lua
require "dep" {
{
"user/dependency",
disabled = true
},
{
"user/package1",
disabled = true, -- implied
requires = "user/dependency"
},
{
"user/package2",
disabled = true, -- implied
requires = "user/dependency"
}
}
```
If a dependency fails to load for some reason, all of its dependents are guaranteed to not load.
```lua
require "dep" {
{
"user/problematic",
function()
error("bad hook")
end
},
{
"user/dependent",
requires = "user/problematic",
function()
print "unreachable"
end
}
}
```
## Separating code into modules
Suppose you split your `init.lua` into two files `packages/search.lua` and
`packages/vcs.lua`, which declare the packages
[telescope.nvim](https://github.com/nvim-telescope/telescope.nvim) and
[vim-fugitive](https://github.com/tpope/vim-fugitive) respectively.
```lua
-- ~/.config/nvim/lua/packages/search.lua:
return {
{
"nvim-telescope/telescope.nvim",
requires = "nvim-lua/plenary.nvim"
}
}
```
```lua
-- ~/.config/nvim/lua/packages/vcs.lua:
return {
"tpope/vim-fugitive"
}
```
Package specifications from other modules can be loaded using the `modules` option.
```lua
require "dep" {
modules = {
prefix = "packages.",
"search",
"vcs"
}
}
-- the above is equivalent to
require "dep" {
modules = {
"packages.search",
"packages.vcs"
}
}
-- which is equivalent to
local packages = {}
for _, package in ipairs(require "packages.search") do
table.insert(packages, package)
end
for _, package in ipairs(require "packages.vcs") do
table.insert(packages, package)
end
require("dep")(packages)
-- which is ultimately equivalent to
require "dep" {
{
"nvim-telescope/telescope.nvim",
requires = "nvim-lua/plenary.nvim"
},
"tpope/vim-fugitive"
}
-- all of the above are guaranteed to load plenary.nvim before telescope.nvim.
-- order of telescope.nvim and vim-fugitive is consistent but unspecified.
```
Entire modules can be marked as disabled, which disables all top-level packages declared in that module.
```lua
return {
disable = true,
{
"user/package",
disabled = true, -- implied by module
requires = {
{
"user/dependency",
-- disabled = true -- not implied
}
},
deps = {
{
"user/dependent",
disabled = true -- implied by dependency
}
}
}
}
```
## Miscellaneous configuration
dep accepts configuration parameters as named fields in the package list.
```lua
require "dep" {
-- [string] Specifies when dep should automatically synchronize.
-- "never": disable this behavior
-- "new": only install newly declared packages (default)
-- "always": synchronize all packages on startup
sync = "new",
-- [array] Specifies the modules to load package specifications from.
-- Defaults to an empty table.
-- Items can be either an array of package specifications,
-- or a string that indicates the name of the module from which the array of package specifications is loaded.
modules = {
-- [string] Prefix string to prepend to all module names.
prefix = "",
},
-- list of package specs...
}
```
## License
dep is licensed under the [MIT License](LICENSE).