{"id":16688487,"url":"https://github.com/hoijui/osh-tool","last_synced_at":"2026-01-02T01:19:29.644Z","repository":{"id":61370902,"uuid":"539023621","full_name":"hoijui/osh-tool","owner":"hoijui","description":"A command line tool for Open Source Hardware (OSH) technical project linting (quality assessment).","archived":false,"fork":false,"pushed_at":"2024-12-23T17:34:36.000Z","size":91160,"stargazers_count":6,"open_issues_count":24,"forks_count":0,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-02-21T17:50:55.475Z","etag":null,"topics":["cli","fchh","hardware","interfacer-project-eu","interfacer-project-eu-wp4-3","open-source-hardware","oseg","tool"],"latest_commit_sha":null,"homepage":"https://hoijui.github.io/osh-tool/","language":"Nim","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"agpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/hoijui.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2022-09-20T14:11:20.000Z","updated_at":"2024-12-23T17:32:38.000Z","dependencies_parsed_at":"2023-11-21T11:45:07.419Z","dependency_job_id":"a648d4be-21ef-4b7b-b280-3daeb2d429d9","html_url":"https://github.com/hoijui/osh-tool","commit_stats":{"total_commits":445,"total_committers":4,"mean_commits":111.25,"dds":0.01573033707865168,"last_synced_commit":"d1cb6f43d262aa88d01a4c2241e605bf330024d4"},"previous_names":[],"tags_count":6,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hoijui%2Fosh-tool","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hoijui%2Fosh-tool/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hoijui%2Fosh-tool/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hoijui%2Fosh-tool/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/hoijui","download_url":"https://codeload.github.com/hoijui/osh-tool/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":243451609,"owners_count":20293168,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cli","fchh","hardware","interfacer-project-eu","interfacer-project-eu-wp4-3","open-source-hardware","oseg","tool"],"created_at":"2024-10-12T15:43:55.236Z","updated_at":"2026-01-02T01:19:29.639Z","avatar_url":"https://github.com/hoijui.png","language":"Nim","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003c!--\nSPDX-FileCopyrightText: 2021 - 2025 Robin Vobruba \u003choijui.quaero@gmail.com\u003e\n\nSPDX-License-Identifier: CC0-1.0\n--\u003e\n\n# `osh`-tool\n\n[![License: AGPL-3.0-or-later](\n    https://img.shields.io/badge/License-AGPL%20v3+-blue.svg)](\n    https://www.gnu.org/licenses/agpl-3.0)\n[![REUSE status](\n    https://api.reuse.software/badge/github.com/hoijui/osh-tool)](\n    https://api.reuse.software/info/github.com/hoijui/osh-tool)\n\n[![In cooperation with FabCity Hamburg](\n    https://raw.githubusercontent.com/osegermany/tiny-files/master/res/media/img/badge-fchh.svg)](\n    https://www.fabcity.hamburg/)\n[![In cooperation with Open Source Ecology Germany](\n    https://raw.githubusercontent.com/osegermany/tiny-files/master/res/media/img/badge-oseg.svg)](\n    https://www.ose-germany.de/die-bewegung/)\n\nA command line tool for Open Source Hardware (OSH)\ntechnical project linting (quality assessment).\n\nYou give this tool a directory containing the documentation and design documents\nabout a technology;\nwhich could be a chair, a tractor, a radio, a dress, shoes ...\nmost anything human made. \\\nThe tool analyzes that directory,\nand then tells you how well organized it thinks the project is.\nThis analysis is made up of tests,\neach of which checks for one [best](https://www.merriam-webster.com/dictionary/best%20practice)-[practice](https://en.wikipedia.org/wiki/Best_practice).\n\nThere are three ways to use this tool:\n\n1. [through CI](#example-projects) (aka build-bot) -\n    We recommend to use this if you host your project in a (git)-repository\n2. [through docker/podman](#docker) -\n    Use this preferably when you want to run it on your local machine.\n3. natively -\n    This (probably) requires you to compile the tool yourself,\n    and also all the required CLI tools\n    (see the [Dockerfile](Dockerfile) for reference).\n    This is **not recommended**,\n    because it is much more work,\n    and it is hard to keep all the required tools up to date.\n\n    Iff you want to use this anyway,\n    you might want to try downloading one of the\n    [prebuilt binaries](https://hoijui.github.io/osh-tool/)\n    (non-static, development=build, Linux \u0026 Windows, 64bit).\n    They are not statically linked though,\n    so you might run into issues with different versions of dynamic libraries\n    (like `libc` or `ssl`).\n\n## Examples\n\n### Badges\n\nTo be used at the top of a README:\n\n- [![Meditation Bench - OSH - Openness](\n    https://hoijui.github.io/MeditationBench/osh-badge-openness.svg)](\n    https://hoijui.github.io/MeditationBench/osh-report.html)\n- [![Agro Circle - OSH - Openness](\n    https://osegermany.github.io/AgroCircle/osh-badge-openness.svg)](\n    https://osegermany.github.io/AgroCircle/osh-report.html)\n- [![OHLOOM - OSH - compliance](\n    https://osegermany.gitlab.io/ohloom/osh-badge-compliance.svg)](\n    \u003chttps://osegermany.gitlab.io/ohloom/osh-report.html\u003e)\n- [![OHLOOM - OSH - machineReadability](\n    https://osegermany.gitlab.io/ohloom/osh-badge-machineReadability.svg)](\n    \u003chttps://osegermany.gitlab.io/ohloom/osh-report.html\u003e)\n- [![OHLOOM - OSH - quality](\n    https://osegermany.gitlab.io/ohloom/osh-badge-quality.svg)](\n    \u003chttps://osegermany.gitlab.io/ohloom/osh-report.html\u003e)\n- [![OHLOOM - OSH - openness](\n    https://osegermany.gitlab.io/ohloom/osh-badge-openness.svg)](\n    \u003chttps://osegermany.gitlab.io/ohloom/osh-report.html\u003e)\n\n### Example Projects\n\nTwo sample hardware projects,\nusing this tool to check their own Open Source'ness\nwith the help of this tool,\nexecuted in [CI](https://en.wikipedia.org/wiki/Continuous_integration).\nThe generated report is linked to form the README in a badge\n(image after the title) with the text \"OSH Report\".\n\n| CI Type | Sample Project Hosting | Generated Report | CI Script |\n| --- | ------ | --- | --- |\n| GitHub Actions | \u003chttps://github.com/hoijui/MeditationBench\u003e | [Generated Report](https://hoijui.github.io/MeditationBench/osh-report.html) | [.github/workflows/check.yml](https://github.com/hoijui/MeditationBench/blob/master/.github/workflows/check.yml) |\n| GitHub Actions 2 | \u003chttps://github.com/osegermany/AgroCircle\u003e | [Generated Report](https://osegermany.github.io/AgroCircle/osh-report.html) | [.github/workflows/check.yml](https://github.com/osegermany/AgroCircle/blob/master/.github/workflows/check.yml) |\n| GitLab CI | \u003chttps://gitlab.com/OSEGermany/ohloom\u003e | [Generated Report](https://osegermany.gitlab.io/ohloom/osh-report.html) | [.gitlab-ci.yml](https://gitlab.com/OSEGermany/ohloom/-/blob/master/.gitlab-ci.yml) |\n\n## Docker\n\n\u003e NOTE\n\u003e Instead of `docker` you may also use the Open Source alternative `podman`\n\u003e in all the code snippets in this section.\n\nThe easiest way to use this tool -\nif you are hosting your project on a git repo that is -\nis through CI (aka build-bot).\nYou can find examples for how to do this\nin the [Example Projects](#example-projects) section. \\\nThe second easiest\nbecause it depends on/uses a lto of other CLI tools,\nmany of which you would have to compile manually!\n\nand the easiest way to use this tool _with docker_,\nis to use the pre-built image hosted in the registry:\n\nYou can download with this command:\n\n```shell\ndocker pull hoijui/osh-tool:latest\n```\n\nAnd execute it in this way\n(NOTE: This gives the docker image read and write access to your current directory):\n\n```shell\ndocker run \\\n    --volume \"$PWD:/data\" \\\n    hoijui/osh-tool:latest \\\n    report_gen \\\n        --force \\\n        --download-badges\n```\n\nYou should then have the report files in the directory `public/`.\n\nIn the above command,\n`report_gen` is a wrapper script around `osh`.\nThink of it as what you generally want to use,\nwhile `osh` is a rather bare-metal tool,\nwhich requires post-processing the generated output for human consumption.\n\nAlternatively,\nyou can also build the docker image on your local machine like so\n(note that here we use `:local` instead of `:latest`):\n\n```shell\ndocker build --tag hoijui/osh-tool:local .\n```\n\nAfter building the image like this,\nit is also in your local registry,\nso you can use it with the `docker run` command from above;\nyou just need to replace `:latest` with `:local`.\nBuilding the image yourself is useful\nif you develop the tool further yourself.\n\n## Features\n\nWhat it does in the rough:\n\n- Check for OSH project design compliance\n- Create human-readable reports\n- Create machine-readable reports\n\nSee [src/checks](src/checks) for the currently supported checks,\nincluding at least:\n\n- Check README existence\n- Check LICENSE existence\n- Check BoM existence\n- Very basic CAD file checks\n- Very basic Electronics CAD file checks\n- Markdown issues\n- Markdown \u0026 HTML link checking\n- Check [okh.toml] ([Open Know-How] OSH meta-data file) existence\n- Check `okh.toml` validity\n- Check detailed licensing information according to REUSE\n- Check if a Version Control System ([VCS]) (like [git]) is used\n- Check if the [VCS] repo is publicly hosted\n- Check if it adheres to the\n  [Open Source Hardware Directory Standard][osh-dir-std]\n\n## Requires\n\nTo compile:\n\n- Nim and Nimble, version 0.10.0 or higher\n\n## Install\n\n### From repository\n\n```sh\n# Fetch the whole source code\ngit submodule update --init --recursive\n# Latest released version\nnimble install osh\n# Latest developmental state inside git repository\nnimble install osh@#head\n```\n\n### From local sources\n\nFor example when using a local git clone.\n\n```sh\nnimble build\n./osh --help\n```\n\n## Usage\n\nSimply run `osh --help` to see usage information.\n\nFor more details how to use it locally and on CI/build-bot,\nsee the [**user documentation**](doc/user/README.md).\n\n## Community\n\nAsk anything as an [issue](https://github.com/hoijui/osh-tool/issues/)!\n\n## Similar Projects\n\nWe are not just standing on the shoulders of giants,\nbut also toe on toe with them!\n\nThese are two of our big sister projects.\nThey are similar both in spirit\nand in the way they are used on the command-line.\nThey also work well in combination with this tool.\n\n- [git] - Master of history\n- [REUSE] -\n  Handles all things regarding licensing of a project and its sources\n\n## License\n\nGNU Affero General Public License version 3\n\n## Funding\n\nThis project was funded by:\n\n- the European Union's [Horizon 2020](\n      https://research-and-innovation.ec.europa.eu/funding/funding-opportunities/funding-programmes-and-open-calls/horizon-2020_en)\n  research and innovation program,\n  under grant agreement no. 869984,\n  in the context of the [OPEN!NEXT Project](https://opennext.eu/),\n  from June 2021 (project start)\n  until November 2021.\n\n  ![Logo of the European Commission](\n      https://commission.europa.eu/themes/contrib/oe_theme/dist/ec/images/logo/positive/logo-ec--en.svg)\n\n- the European Regional Development Fund (ERDF)\n  in the context of the [INTERFACER Project](https://www.interfacerproject.eu/),\n  from December 2021\n  until March 2023.\n\n  ![Logo of the EU ERDF program](\n      https://cloud.fabcity.hamburg/s/TopenKEHkWJ8j5P/download/logo-eu-erdf.png)\n\n[okh.toml]: https://github.com/iop-alliance/OpenKnowHow/blob/master/res/sample_data/okh-TEMPLATE.toml\n[Open Know-How]: https://www.internetofproduction.org/openknowhow\n[VCS]: https://www.geeksforgeeks.org/version-control-systems/\n[git]: https://git-scm.com/\n[REUSE]: https://git.fsfe.org/reuse/tool\n[osh-dir-std]: https://gitlab.com/OSEGermany/osh-dir-std/\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhoijui%2Fosh-tool","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fhoijui%2Fosh-tool","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhoijui%2Fosh-tool/lists"}