Module Management with slp

slp automates a number of things that absolutely can but done without it... but it makes things a whole lot easier. In this document we'll go through the available options of the program and dig a little under the hood at what is happening.

This document is intended to guide you through using the slp software and the package registry. For more information about modules in general please see the main slope documentation.

Installing slp

slp is easy to install. It comes with a makefile that is both BSD and GNU make compatible. You can build the program locally or opt to install it globally. Opting to do the later also installs the manpage. To install this way you will need git, golang >= 1.16, and make. Most non-windows systems should have git and make already installed. So if you do not have go installed on your system, check with your package manager or go to go's download page.


# Get the source code and build it
git clone https://git.rawtext.club/slope-lang/slp
cd slp && sudo make install

# To build locally:
#
#    cd slp && make
#
# Then move the slp binary to
# where you want it.
            

Getting Package Information

Getting information about the availability of packages is an important part of package management. In this section we will cover various ways of finding packages, finding information/meta-data about packages, and seeing what packages are currently available to the the given $USER.

Listing Available Packages

It is easy to get a full list of every package offered in the registry by running the list command. When you do so a request will be made to the registry to get an updated package list (if one has not been acquired recently). Each package will be listed in alphabetical order along with a link to its git repository and a brief description of the package. This approach can turn into a bit of a firehose as the registry grows. As such, using the search command may serve you better under certain circumstances.


slp list
            

Searching for packages is an efficient way to find what you are looking for. The search term you provide will be used to search each package's title and description. It is a straight match, so searching for ini parser will look for that exact phrase. In that example, you might be better served by searching for ini since the words are not taken as individual search terms.

Each package that matches the search will be printed to the output in the same manner that the list command does: with package name, description, and git url.


# slp search [search_string]
slp search "csv"

# Output:
#
# searching for csv:
#
# csv / https://git.rawtext.club/samhunter/csv
#  A module for working with csv files
            

Listing Installed Packages

To see what packages you currently have on the system you can use the installed command. It will provide a list of all of the packages you have installed locally (for your user). The installed command accepts an optional -g flag that will search for modules that have been installed globally (for the system, not just your user).


# See user packages
slp installed

# See system packages
slp installed -g
            

Showing Package Details

You can view information for packages with the show command, for both available and installed packages. The package listing will show the package name, a description, the author, the version, the package's git repository url, the current git tag, a homepage url if available, and a list of any dependencies the package has.


slp show csv

# Output:
#
# csv
#   ├ Description: A module for working csv files
#   ├ Author: samhunter
#   ├ Version: 0.1.0
#   ├ Repository: https://git.rawtext.club/samhunter/csv
#   ├ Tag: v0.1.0
#   ├ Homepage:
#   └ Dependencies: no dependencies 
            

Installing Packages

The install command allows you to download and "install" (move to the correct directory) packages. When you request the install of a package the package list will be downloaded (if it was not downloaded recently). If the requested package is in the package list and not already installed it will be downloaded to a temporary directory. The current release tag will be checked out. The package will be validated (checked for required files). This process will be followed for any dependencies the requested package has. If there are errors/issues along the way, they will be reported to you.

If the -g flag is passed after the install command (but before the package name) the package will be installed globally.


# install for the local user
slp install ini

# install globally
slp install -g ini
            

Removing Packages

The remove command allows you to remove installed packages from the system. When you request the removal of a package slp will check that it is present on the system. If the package is present, it is deleted. This cannot be undone, but the package can likely be installed again if need be.

If the -g flag is passed after the remove command (but before the package name) the package will be removed from the global installation directory.


# remove for the local user
slp remove ini

# remove globally
slp remove -g ini
            

Generating a New Package

The gen command will create a new module skeleton that includes a folder named for the module, a main.slo file with some boilerplate code and comments in it, a module.json file, and will make the folder a git repository. When you enter slp gen you will be asked a series of questions. Some will require answers, others will be optional. Note that some of the optional fields are required in order to submit a module to the slp package registry, but are left optional since the information may not be available at the time of generation. The new folder gets created as a child of the current working directory.

gen is a convenience function to let you skip a few steps when starting a new project. Everything that it does can also be done manually with relative ease.


slope gen
            

Adding a Package to the Registry

If you end up making your own module/package you may want to share that code with others. The easiest way to share it with the slope community is via the slp package registry.

The current setup can be a little cumbersome and overwhelming for those not familiar with git or without accounts at git.rawtext.club. The package add steps are hopefully clear enough to get you there, though there is still the problem of needing an account on git.rawtext.club. You may not have one, they may not be available, or you may not want one. So what to do? We are still working that out. If you have an e-mail contact you can use it to send a diff for packages.json and we can manually update. Once a dedicated public e-mail address is available this information will get updated and patches will be able to be sent by e-mail or possibly by some other means. Stay tuned

Package Add Instructions

  1. Fork the slp package registry. This can be done by using the fork feature on git.rawtext.club
  2. Add the contents of your module's module.json file to the package repository's packages.json file. Make sure all of the following have been done first:
    • Update your module.json file with the version you will be at when you push to the repo, also come up with a tag name for that version and enter it in your module.json file
    • Commit your changes (git commit -m "Updates version and tag for release to slp packages repo")
    • Add a tag matching the tag name you entered in your module.json file (git tag my-tag-name, but with your own tag name)
    • Push your commit and tag. If you were on your master branch and your tag was my-tag-name: git push origin master && git push origin my-tag-name. Sadly, git does not automatically push tags
  3. Commit the changes in your fork of the packages repository and push them to your fork/remote
  4. Open a pull request from your fork into the master branch of the packages repository