OSH directory standard - Rust library

• OSH: Open Source Hardware

Code that helps humans and machines deal with the OSH directory standard.

This consists of two parts:

1. osh_dir_std - a (Rust) library to parse the specification(s) into easily usable structures & accompanying utilities
2. osh-dir-std - a CLI tool that helps checking a given projects file listing against one or multiple specifications.

NOTE
This only checks the paths of files and directories against a set of presets (aka "standards"). It does not check the content of any files in any way.

Example Usage

CLI

Installation

From Source

Fetch & Compile

cargo install osh-dir-std

Local Sources

cargo install --path bin

Usage

The tool expects a new-line separated listing of files (and optionally directories) of the project, either on stdin, or in a file given as the first argument. This list might come from git (or any other version control system (VCS) used), the file-system directly, a ZIP file or even a web-site that lists the files.

A few examples of how to list files in different scenarios, to rate the project against the known directory standards:

git:

git ls-files --recurse-submodules | sed -e 's/^"\(.*\)"$/\1/' | osh-dir-std rate

SVN:

svn ls | osh-dir-std rate

Mercurial (hg):

hg status --all | osh-dir-std rate

pijul:

pijul list | osh-dir-std rate

file-system:

ls -r1 | osh-dir-std rate

sample output:

[
  {
    "name": "unixish",
    "factor": 0.62724684
  },
]

A factor of 1.0 would mean that the projects file- and directory structure adheres 100% to the respective standard. unixish is the name of the default directory standard.

Library

Setup

Cargo.toml:

[dependencies]
osh_dir_std = "0.7.2"

Code

use osh_dir_std::{self, format::Rec};

fn find_rec(std: &str, record_path: &str) -> Result<&'static Rec<'static>, String> {
    for rec in &osh_dir_std::data::STDS.get(std).unwrap().records {
        if rec.path == record_path {
            return Ok(rec);
        }
    }
    Err(format!(
        "Failed to find record with path '{record_path}' in the '{std}' dir standard"
    ))
}

/// Checks whether the dir std "unixish" contains the record "res/",
/// and whether that record is a _fixed_ one. See [the definition](
/// https://github.com/hoijui/osh-dir-std/blob/main/definition_format.csv)
/// for an explanation of what _fixed_ means.
#[test]
fn unixish_res_fixed() -> Result<(), Error> {
    let rec = find_rec("unixish", "res/")?;
    assert!(rec.fixed);
    Ok(())
}

Related Projects

• osh-tool - Checks an OSH project against a set of predefined checks, to try to assess its overall machine-readability and openness.
  (also uses this tool internally)

Funding

This project was funded by the European Regional Development Fund (ERDF) in the context of the INTERFACER Project, from November 2022 (project start) until March 2023.