From 53d90a2949242075ed44cfea80454294bd76b334 Mon Sep 17 00:00:00 2001 From: Tom Alexander Date: Wed, 13 Sep 2023 20:07:21 -0400 Subject: [PATCH] Update the README to have instructions on running the tests and development programs. --- README.md | 55 +++++++++++++++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 53 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index f45c108e..467b285c 100644 --- a/README.md +++ b/README.md @@ -2,12 +2,63 @@ Organic is an emacs-less implementation of an [org-mode](https://orgmode.org/) parser. - ## Project Status This project is a personal learning project to grow my experience in [rust](https://www.rust-lang.org/). It is under development and at this time I would not recommend anyone use this code. The goal is to turn this into a project others can use, at which point more information will appear in this README. +## Using this library +TODO: Add section on using Organic as a library (which is the intended use for this project). + +### The parse binary +This program takes org-mode input either streamed in on stdin or as paths to files passed in as arguments. It then parses them using Organic and dumps the result to stdout. This program is intended solely as a development tool. Examples: +```bash +cat /foo/bar.org | cargo run --bin parse +``` +```bash +cargo build --profile release-lto +./target/release-lto/parse /foo/bar.org /lorem/ipsum.org +``` + +### The compare binary +This program takes org-mode input either streamed in on stdin or as paths to files passed in as arguments. It then parses them using Organic and the official Emacs Org-mode parser and compares the parse result. This program is intended solely as a development tool. Since org-mode is a moving target, it is recommended that you run this through docker since we pin the version of org-mode to a specific revision. Examples: +```bash +cat /foo/bar.org | ./scripts/run_docker_compare.bash +``` +```bash +./scripts/run_docker_compare.bash /foo/bar.org /lorem/ipsum.org +``` + +Not recommended since it is not through docker: + +```bash +cat /foo/bar.org | cargo run --features compare --bin compare +``` +```bash +cargo build --profile release-lto --features compare +./target/release-lto/compare /foo/bar.org /lorem/ipsum.org +``` + +## Running the tests +There are three levels of tests for this repository: the standard tests, the autogenerated tests, and the foreign document tests. + +### The standard tests +These are regular hand-written rust tests. These can be run with: +```bash +make unittest +``` + +### The auto-generated tests +These tests are automatically generated from the files in the `org_mode_samples` directory and they are still integrated with the rust/cargo testing framework. For each org-mode document in that folder, a test is generated that will parse the document with both Organic and the official Emacs Org-mode parser and then it will compare the parse results. Any deviation is considered a failure. Since org-mode is a moving target, it is recommended that you run these tests inside docker since the `organic-test` docker image is pinned to a specific revision of org-mode. These can be run with: +```bash +make dockertest +``` + +### The foreign document tests +These tests function the same as the auto-generated tests except they are **not** integrated with the rust/cargo testing framework and they involve comparing the parse of org-mode documents that live outside this repository. This allows us to test against a far greater variety of org-mode input documents without pulling massive sets of org-mode documents into this repository. The recommended way to run these tests is still through docker because it pins org-mode and the test documents to specific git revisions. These can be run with: +```bash +make foreign_document_test +``` ## License -This project is released under the public-domain-equivalent [0BSD license](https://www.tldrlegal.com/license/bsd-0-clause-license). This license puts no restrictions on the use of this code (you do not even have to include the copyright notice or license text when using it). HOWEVER, this project has a couple permissively licensed dependencies which do require their copyright notices and/or license texts to be included. I am not a lawyer and this is not legal advice but it is my layperson's understanding that if you distribute a binary with this library linked in, you will need to abide by their terms since their code will also be linked in your binary. I try to keep the dependencies to a minimum and the most restrictive dependency I will ever include is a permissively licensed one. +This project is released under the public-domain-equivalent [0BSD license](https://www.tldrlegal.com/license/bsd-0-clause-license), however, this project has a couple permissively licensed non-public-domain-equivalent dependencies which require their copyright notices and/or license texts to be included. I am not a lawyer and this is not legal advice but it is my layperson's understanding that if you distribute a binary statically linking this library, you will need to abide by their terms since their code will also be linked in your binary.