You cannot select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
80 lines
2.6 KiB
Markdown
80 lines
2.6 KiB
Markdown
9 years ago
|
# Creating
|
||
9 years ago
|
|
||
9 years ago
|
To learn package creation let's create a new package that will provide a `hello_world` command for your shell. Package names may only contain lowercase letters and hyphens to separate words.
|
||
9 years ago
|
|
||
9 years ago
|
Oh My Fish can scaffold a package structure for you. Use the command `omf new`:
|
||
9 years ago
|
|
||
|
```fish
|
||
9 years ago
|
$ omf new pkg hello_world
|
||
9 years ago
|
```
|
||
|
|
||
9 years ago
|
> Use `omf new theme my_theme_name` for themes.
|
||
9 years ago
|
|
||
9 years ago
|
The utily changes the current directory to the newly created package:
|
||
9 years ago
|
|
||
9 years ago
|
```
|
||
|
$ ls -l
|
||
|
README.md
|
||
|
hello_world.fish
|
||
|
completions/hello_world.fish
|
||
|
```
|
||
9 years ago
|
|
||
9 years ago
|
Always describe how your package works in the `README.md`. Also read more about [auto completion](http://fishshell.com/docs/current/commands.html#complete) and also take care to provide it for your utilities when applicable.
|
||
9 years ago
|
|
||
9 years ago
|
`hello_world.fish` defines a single function:
|
||
9 years ago
|
|
||
|
```fish
|
||
9 years ago
|
function hello_world -d "Prints hello world"
|
||
|
echo "Hello World!"
|
||
|
end
|
||
9 years ago
|
```
|
||
|
|
||
9 years ago
|
Each function in your package must be declared in its own file. This is required by fish autoloading mechanism, which loads functions on demand, avoiding loading unused functions.
|
||
9 years ago
|
|
||
9 years ago
|
Bear in mind that fish lacks a private scope, so if you need to split your package into functions, consider prefixing private functions like this: `__hello_world.my_extra_function`, to avoid both name clashes and global namespace pollution.
|
||
9 years ago
|
|
||
9 years ago
|
# Events
|
||
9 years ago
|
|
||
9 years ago
|
Packages were designed to take advantages of fish events. There are currently two events that Oh My Fish will emit to your package:
|
||
9 years ago
|
|
||
|
## Initialization
|
||
|
|
||
9 years ago
|
If you want to be [notified](http://fishshell.com/docs/current/commands.html#emit) when your package loads, declare the following function in your `hello_world.fish`:
|
||
9 years ago
|
|
||
|
```fish
|
||
9 years ago
|
function init -a path --on-event init_hello_world
|
||
|
echo "hello_world initialized"
|
||
9 years ago
|
end
|
||
|
```
|
||
|
|
||
|
Use this event to modify the environment, load resources, autoload functions, etc. If your package does not export any functions, you can still use this event to add functionality to your package.
|
||
|
|
||
|
## Uninstall
|
||
|
|
||
|
Oh My Fish emits `uninstall_<pkg>` events before a package is removed via `omf remove <pkg>`. Subscribers can use the event to clean up custom resources, etc.
|
||
|
|
||
|
```fish
|
||
9 years ago
|
function uninstall --on-event uninstall_hello_world
|
||
9 years ago
|
end
|
||
|
```
|
||
|
|
||
|
|
||
9 years ago
|
# Make it public
|
||
|
|
||
|
Oh My Fish keeps a registry of public packages under `$OMF_PATH/db/`.
|
||
|
|
||
|
To add your package to the registry you need to:
|
||
|
|
||
|
```fish
|
||
|
# For packages:
|
||
|
omf submit pkg/hello_world .../hello_world.git
|
||
|
|
||
|
# For themes
|
||
|
omf submit theme/my_theme .../my_theme_name.git
|
||
|
```
|
||
|
|
||
|
This will add a new entry to your local copy of the registry. Now you just need to [send us a PR][omf-pulls-link] to update the global registry.
|
||
|
|
||
|
|
||
9 years ago
|
[omf-pulls-link]: https://github.com/oh-my-fish/oh-my-fish/pulls
|