DevelopingPackages

Developing Packages

I would recommend taking a look at existing ones.

Development Environment

Due to NuShell's nature there is (to my knowledge) no good editor for .nu files.

The best compromise i have found is:

• Editor: NeoVim
• Package-Manager: Packer.nvim (info) (any modern one will do, but i recommend this one)
• Syntax-Highlight Framework: nvim-treesitter/nvim-treesitter (info)
• A treesitter compatible colorscheme: binhtran432k/dracula.nvim (improve branch) (Info)
• Syntax-Highlight: LhKipp/nvim-nu (info) (this is really outdated and buggy, but there's no alternative) (the null-lsp integration does not work anymore)

The meta.nuon

This is the only required feature of a package.

It is a file in the base of your project called meta.nuon, which instructs packer.nu on how to load your package.

A example:

{
	version: [1 0 0]
	description: 'My first package'
	copyright: '2022 Bob (example@gmail.com)'
	license: 'Boost Software License - Version 1.0'
	url: 'https://github.com/foo/bar'
	min_nu_version: [0 68 0]
	max_nu_version: [0 72 0]
	min_packer_version: [2 0 0]
	max_packer_version: [2 0 0]
	modules: ['foo', 'dir/bar']
	prefixed_modules: ['cargo']
}

Explanation

Field	required	type	description
description	true	string	A description.
version	true	version_code	The package version.
copyright	false	string	A copyright (freeform).
license	false	string	The name of (+link to) your license.
url	false	string	A url to the website / git / ...
modules	false	list	Package Modules (relative path from meta.nuon without file extension).
prefixed_modules	false	list	modules, which are imported with their filename as prefix.
min_nu_version	false	version_code	The oldest nushell version it supports.
max_nu_version	false	version_code	The newest nushell version it supports.
min_packer_version	false	version_code	The oldest packer.nu version it supports.
max_packer_version	false	version_code	The newest packer.nu version it supports.

Type version_code: This is not a actual type, but just a list containing 3 integers:

1. Mayor version
2. Minor version
3. Patch (a patch does NOT contain breaking changes) (patches in compatability-settings are ignored)

The env.nu

This file is loaded via source-env PATH and therefore is able to set some environmental variables.

example:

export-env {
	let-env FOO = 'BAR'
}

The init.nu

This file is loaded as a unprefixed module.

example:

export alias nano = vim
export def filecount [] {ls | length}
export external vim [
	...files: path
]

Modules

Modules are files, which are imported via use.

Example: cargo.nu (registered via prefixed_modules as cargo)

export def install [...names: string] {
	^cargo install $names
}

export def search [text: string] {
	^cargo search $text | from ssv
}

Unprefixed modules are imported via use FILE *

The lib directory

You can have a lib directory, which will be added to $env.NU_LIB_DIRS.

This can be useful for optional modules, overlays, and libraries used by multiple packages.

Since there are no naming guidelines yet, i would like to introduce some:

• libs, which are meant for overlay use .. should use .o file extension (overlay)

Special files

post_install.nu

This file is executed (nu PACKAGE/post_install.nu) once after the initial installation.

It can be used to create configuration files, install dependencies, and everything else you might need to do.

Adding configuration

Packages can be configured by the user in the packages.nuon.

The content of config for your plugin will be stored in $env.NU_PACKER_CFG.PLUGIN_NAME (where PLUGIN_NAME is escaped using $your_plugin_name | str replace '[^a-zA-Z0-9]' '_' -> packer.nu is packer_nu).

Since the user might not have configured anything for your plugin it is recommended to access it using something along the lines of $env.NU_PACKER_CFG | get -i packer_nu.example_variable | default true.