sliderule-cli

Introduction

This is a command line implementation of the distributed open source hardware (OSHW) DOF methodology being developed by Mach 30.

NOTE This is in the very early stages of development, and is not ready for widespread use.

Installation

git and npm must be installed separately for sliderule-cli to work. Binaries for sliderule-cli are avaiable for Linux, Windows and MacOS.

Windows

• Install git
• Install npm
• Download the latest Windows build of sliderule-cli.
• Extract the archive to a convenient location (i.e. C:\Users\[you]\).
• Run the command with the full path (i.e. C:\Users\[you]\sliderule-cli\sliderule-cli.exe).

Optionally, it is possible to set an alias within Windows Powershell for the CLI to make it more convenient to run:

PS C:\> Set-Alias sr C:\Users\[you]\sliderule-cli\sliderule-cli.exe

Unfortunately, at this time the passphrase has to be removed from the private key for the CLI to work. Follow the instructions here to do that.

Linux

• Install git
• Install npm
• Download the latest x86_64 Linux build (most computers) or the latest arm64 Linux build (Raspberry Pi and Pinebook) of sliderule-cli.
• Extract the archive to a location in the PATH environment variable (i.e. ~/bin).
• Run the command with the full path (i.e. ~/bin/sliderule-cli/sliderule-cli).

Optionally, it is possible to create a symbolic link to make it more convenient to run the CLI:

$ ln -s ~/bin/sliderule-cli/sliderule-cli ~/bin/sr

MacOS

• Install git
• Install npm
• Download the latest MacOS build of sliderule-cli.
• Extract the archive to a location in the PATH environment variable (i.e. ~/Applications).
• Run the command with the full path (i.e. ~/Applications/sliderule-cli/sliderule-cli).

Optionally, it is possible to create a symbolic link to make it more convenient to run the CLI (assuming ~/bin is in your PATH):

$ ln -s ~/Applications/sliderule-cli/sliderule-cli ~/bin/sr

Usage

Creating and Managing a Sliderule Component

Everything in Sliderule is a component, even the top level "project" component that holds all other components. In this way, your top level project can be used as a component of another project later on. The workflow for creating, initializing and populating a new project is as follows.

1. Run sliderule-cli create [name] in a directory that you have access to, and that is not already a component directory.
2. Change (cd) into the newly created component directory, with the name provided as the name argument from step 1.
3. Use sliderule-cli add [url] to begin pulling remote components into the project.
4. Use sliderule-cli create [name] to create new local components within your project.
5. Add and change project source files in each local component as needed to complete your design.
6. Use sliderule-cli downloadto download the latest changes for your project/component and for any remote componenets.
7. Use sliderule-cli upload and provide a message when prompted to upload all of the changes made within the project's file structure to its remote repository. If the current project is not set up for a remote repository, the CLI will prompt for a URL. The remote repository must already exist, and is not created by the CLI.

Command Listing

• sliderule-cli create [name] [-s SOURCE_LICENSE] [-d DOCUMENTATION_LICENSE] - Creates a new component.
  • If the current directory is not a component, a name directory is created in the current directory, assuming the user has write access. The new directory is then initialized as a new top-level Sliderule project component, with files and directories being created as needed to match the Sliderule methodology.
  • If the current directory is already a component, creates a new local component name from scratch and places it within the components directory of the current project.
• sliderule-cli download [all | dependencies | component_url] - Downloads updates for the Sliderule project in the current directory.
  • all (default) - Downloads all changes to the component and its dependencies, assuming the current directory holds a Sliderule component.
  • dependencies - Downloads updates for only dependency components, assuming that the current directory is a Sliderule component.
  • component_url - Makes a copy of an existing remote component at the given URL. This creates a new directory for the downloaded component. Unless a user is an owner or maintainer of the remote component's repository, the downloaded component is read-only.
• sliderule-cli upload [-m MESSAGE] [-u REMOTE_URL] - Asks for (or accepts) a message to attach to any changes, and uploads all project/component changes. If the current component directory has not been initilized for a remote repository, the user is prompted to enter the repository's URL unless it was specified as a command line option.
• sliderule-cli add [url] - Downloads a remote component and installs it in the current project. Unless a user is an owner or maintainer of the remote component's repository, remote components are read-only. If using a git host such as GitHub, the https URL must be used, instead of the SSH link. The URL provided can be from any supported repository type, such as git on GitHub: https://github.com/m30-jrs/blink_firmware.git
• sliderule-cli remove [-y] [name] - Removes the named component from a project. The name can refer to either a local or remote component. The the y option is included, the user is not prompted before the component is removed.
• sliderule-cli refactor [name] [-u REMOTE_URL] - Changes a local component to a remote component. This command will ask for a URL for the component to be pushed to unless the remote URL was specified as a command line option. The specified URL must exist prior to running this command. The remote repository for the component is not created automatically at this time. Use the SSH link to the repository if hosted on GitHub, GitLab, Git* instead of the https link, and make sure to have your ssh keys set up correctly for your operating system.
• sliderule-cli licenses change [-s SOURCE_LICENSE] [-d DOCUMENTATION_LICENSE] - Changes the source and/or documentation licenses of the current component.
• sliderule-cli licenses list - Lists all of the licenses that are active for the current component.

Options

• -y - Answers yes to all questions for unattended operation.
• -v - Provides verbose output that is helpful when debugging why an operation failed.

Building

sliderule-rs needs to be cloned into the same parent directory as this CLI before the following steps are followed.

If Rust is installed on a Linux, Windows or Mac computer, follow the instructions for your platform below to build the program.

cargo build [--release]

After Build - Linux & MacOS

Once the build has completed successfully, the sliderule-cli binary should be located in sliderule-cli/target/debug/. Supply the full path to the sliderule-cli binary to use it. Alternatively, add the path to sliderule-cli to the PATH environment variable. Using a symbolic link or alias will allows for use a short command name like sr for convenience.

After Build - Windows

Once the build has completed successfully, the sliderule-cli.exe binary should be located in .\sliderule-cli\target\debug\. Supply the full path to the sliderule-cli.exe binary to use it. Alternatively, add the path to sliderule-cli.exe to the PATH environment variable. Setting an alias allows for use of a short command name like sr for convenience.

Running Tests

sliderule-rs needs to be cloned into the same parent directory as this CLI before these steps are followed.

If Rust is installed, running the following command in the root sliderule-cli directory will execute the tests.

cargo test -- --test-threads=1

The test-threads option is very important. If the tests are run in parallel (the default for cargo), they will fail randomly because they will interfere with each other.