Skip to content
Application microframework with command-line option parsing, configuration, error handling, logging, and shell interactions
Rust HTML
Branch: develop
Clone or download
tony-iqlusion Merge pull request #134 from iqlusioninc/1-x-proc-macro-crates
derive: Update to 1.0 versions of proc-macro2/quote/syn
Latest commit 4eea45e Aug 24, 2019

README.md

Abscissa

Crate Docs Apache 2.0 Licensed MSRV forbid(unsafe_code) Build Status Appveyor Status Gitter Chat

Abscissa is a microframework for building Rust applications (either CLI tools or network/web services), aiming to provide a large number of features with a minimal number of dependencies, and with a strong focus on security.

Documentation

Features

  • command-line option parsing: simple declarative option parser based on gumdrop. The option parser in Abcissa contains numerous improvements which provide better UX and tighter integration with the other parts of the framework (e.g. overriding configuration settings using command-line options).
  • components: Abscissa uses a component architecture (similar to an ECS) for extensibility/composability, with a minimalist implementation that still provides such features such as calculating dependency ordering and providing hooks into the application lifecycle. Newly generated apps use two components by default: terminal and logging.
  • configuration: Simple parsing of TOML configurations to serde-parsed configuration types which can be dynamically updated at runtime.
  • error handling: generic Error type based on the failure crate, and a unified error-handling subsystem.
  • logging: based on the log to provide application-level logging.
  • secrets management: the (optional) secrets module includes a Secret type which derives serde's Deserialize and can be used to represent secret values parsed from configuration files or elsewhere (e.g. credentials loaded from the environment or network requests)
  • terminal interactions: support for colored terminal output (with color support autodetection). Useful for Cargo-like status messages with easy-to-use macros.

Projects Using Abscissa

  • Tendermint KMS: key management system for Tendermint applications
  • canister: deployment utility for "distroless" containers/microVMs
  • cargo-audit: audit Cargo projects for security vulnerabilities
  • cargo-rpm: build RPMs out of Cargo projects
  • sagan: observability tool for Tendermint applications

Crate Structure

Abscissa presently consists of three crates:

  • abscissa: CLI app and application generator - cargo install abscissa
  • abscissa_core: main framework library
  • abscissa_derive: custom derive support - implementation detail of abscissa_core

Requirements

  • Rust 1.36+

Installation

To generate a new Abscissa application, install the abscissa CLI utility:

$ cargo install abscissa

Usage

After installing the abscissa CLI utility using the method above, run abscissa new <my_app> to generate a new application:

This will generate a new Abscissa application in the my_cool_app directory. For more information, please see the Documentation.

Depencencies

or: "Know Your Dependencies"

One of Abscissa's primary goals is to maximize functionality while minimizing the number of dependencies. Abscissa is used in a number of high-security contexts, and as such we view each additional dependency as additional attack surface and therefore a potential liability. We have therefore been very conscientious about the dependencies we use and will not add additional dependencies without due consideration.

Here are all of Abscissa's transitive dependencies when configured with the default set of features in the application:

# Crate Name Origin License Description
1 abscissa_core iqlusion Apache-2.0 Abscissa framework
2 arc-swap @vorner Apache-2.0/MIT Atomic swap for Arc
3 autocfg @cuviper Apache-2.0/MIT Rust compiler configs
4 backtrace @alexcrichton Apache-2.0/MIT Capture stack traces
5 backtrace-sys @alexcrichton Apache-2.0/MIT Capture stack traces
6 canonical-path iqlusion Apache-2.0 Get canonical fs paths
7 chrono chronotope Apache-2.0/MIT Time/date library
8 failure @withoutboats Apache-2.0/MIT Error handling
9 generational-arena @fitzgen MPL-2.0 Component allocator
10 gumdrop @Murarth Apache-2.0/MIT Command-line options
11 lazy_static rust-lang Apache-2.0/MIT Heap-allocated statics
12 libc rust-lang Apache-2.0/MIT C library wrapper
13 log rust-lang Apache-2.0/MIT Logging facade library
14 num-integer rust-num Apache-2.0/MIT Integer trait
15 num-traits rust-num Apache-2.0/MIT Numeric traits
16 redox_syscall redox-os MIT Redox OS syscall API
17 rustc-demangle @alexcrichton Apache-2.0/MIT Symbol demangling
18 secrecy iqlusion Apache-2.0 Secret-keeping types
19 semver @steveklabnik Apache-2.0/MIT Semantic versioning
20 semver-parser @steveklabnik Apache-2.0/MIT Parser for semver spec
21 serde serde-rs Apache-2.0/MIT Serialization framework
22 signal-hook @vorner Apache-2.0/MIT Unix signal handling
23 signal-hook-registry @vorner Apache-2.0/MIT Unix signal registry
24 termcolor @BurntSushi MIT/Unlicense Terminal color support
25 time rust-lang Apache-2.0/MIT Time/date library
26 toml @alexcrichton Apache-2.0/MIT TOML parser library
27 winapi§ @retep998 Apache-2.0/MIT Windows FFI bindings
28 winapi-util @BurntSushi MIT/Unlicense Safe winapi wrappers
29 wincolor @BurntSushi MIT/Unlicense Windows console color
30 zeroize iqlusion Apache-2.0/MIT Zero out sensitive data

Build / Development / Testing Dependencies

# Crate Name Origin License Description
1 abscissa_derive iqlusion Apache-2.0 Abscissa custom derive
2 aho-corasick @BurntSushi MIT/Unlicense Pattern-matching alg
3 cc @alexcrichton Apache-2.0/MIT C/C++ compiler wrapper
4 cfg-if @alexcrichton Apache-2.0/MIT If-like #[cfg] macros
5 darling @TedDriggs MIT Nifty attribute parser
6 darling_core @TedDriggs MIT Attribute parser core
7 darling_macro @TedDriggs MIT Attribute parser macros
8 failure_derive @withoutboats Apache-2.0/MIT failure custom derive
9 fnv @alexcrichton Apache-2.0/MIT Fast hash function
10 gumdrop_derive @Murarth Apache-2.0/MIT Command-line options
11 ident_case @TedDriggs Apache-2.0/MIT Case conversion utils
12 memchr @BurntSushi MIT/Unlicense Optimized byte search
13 proc-macro2 @alexcrichton Apache-2.0/MIT Shim for Macros 2.0 API
14 quote @dtolnay Apache-2.0/MIT Rust AST to token macro
15 regex rust-lang Apache-2.0/MIT Regular expressions
16 regex-syntax rust-lang Apache-2.0/MIT Regex syntax impl
17 serde_derive serde-rs Apache-2.0/MIT serde custom derive
18 strsim @dguo MIT String similarity utils
19 syn @dtolnay Apache-2.0/MIT Rust source code parser
20 synstructure @mystor Apache-2.0/MIT syn structure macros
21 thread_local @Amanieu Apache-2.0/MIT Per-object thread local
22 ucd-util @BurntSushi Apache-2.0/MIT Unicode utilities
23 unicode-xid unicode-rs Apache-2.0/MIT Identify valid Unicode
24 utf8-ranges @BurntSushi MIT/Unlicense UTF-8 codepoint ranges
25 wait-timeout @alexcrichton Apache-2.0/MIT Timeouts for waitpid

Dependency Relationships

The table below should help answer questions as to why a particular crate is an Abscissa dependency and whether or not it is optional. Abscissa uses cargo features to allow parts of it you aren't using to be easily disabled, so you only compile the parts you need.

Crate Name Cargo Features Required By
abscissa_core -
abscissa_derive - abscissa_core
aho-corasick testing regex
arc-swap signals signal-hook-registry
autocfg time num-integer
backtrace - failure
backtrace-sys - backtrace
canonical-path - abscissa_core
cc - backtrace-sys
cfg-if - backtrace, log
chrono time abscissa_core
darling - abscissa_derive
darling_core - darling, darling_macro
darling_macro - darling
failure - abscissa_core
failure_derive - failure
fnv - darling_core
generational-arena application abscissa_core
gumdrop options abscissa_core
gumdrop_derive options gumdrop
ident_case - abscissa_derive, darling_core
lazy_static - abscissa_core
libc signals abscissa_core
log logging abscissa_core
memchr testing aho-corasick
num-integer time chrono
num-traits time chrono, num-integer
proc-macro2 - abscissa_derive, darling, failure_derive, quote, serde_derive, syn
quote - abscissa_derive, darling, failure_derive, gumdrop_derive, serde_derive
redox_syscall time time
regex testing abscissa_core
rustc-demangle - backtrace
secrecy secrets abscissa_core
semver application abscissa_core
semver-parser application abscissa_core
serde config abscissa_core
serde_derive config serde
signal-hook signals abscissa_core
signal-hook-registry signals signal-hook
strsim - darling_core
syn - abscissa_derive, darling, failure_derive, gumdrop_derive, serde_derive
termcolor terminal abscissa_core
thread_local testing regex
time logging chrono
ucd-util testing regex-syntax
unicode-xid - proc-macro2, syn
utf8-ranges testing regex
wait-timeout testing abscissa_core
winapi§ - termcolor, time, winapi-util
winapi-util - termcolor
zeroize - abscissa_core

Frequently Asked Questions (FAQ)

Q1: Why is it called "abscissa"?

A1: The word "abscissa" is the key to the Kryptos K2 panel.

Q2: "Abscissa" is a hard name to remember! Got any tips?

A2: Imagine you're A-B testing a couple of scissors... with attitude.

Testing Framework Changes

The main way to test framework changes is by generating an application with Abscissa's built-in application generator and running tests against the generated application (also rustfmt, clippy).

To generate a test application and test it automatically, you can simply do:

$ cargo test

However, when debugging test failures against a generated app, it's helpful to know how to drive the app generation and testing process manually. Below are instructions on how to do so.

If you've already run:

$ git clone https://github.com/iqlusioninc/abscissa/

...and are inside the abscissa directory and want to test your changes, you can generate an application by running the following command:

$ cargo run -- new /tmp/example_app --patch-crates-io='abscissa = { path = "$PWD" }'

This will generate a new Abscissa application in /tmp/example_app which references your local copy of Abscissa.

After that, change directory to the newly generated app and run the tests to ensure things are still working (the tests, along with rustfmt and clippy are run as part of the CI process):

$ cd /tmp/example_app # or 'pushd /tmp/example_app' and 'popd' to return
$ cargo test
$ cargo fmt -- --check # generated app is expected to pass rustfmt
$ cargo clippy

Code of Conduct

We abide by the Contributor Covenant and ask that you do as well.

For more information, please see CODE_OF_CONDUCT.md.

License

The abscissa crate is distributed under the terms of the Apache License (Version 2.0).

Copyright © 2018-2019 iqlusion

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

https://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

Contribution

If you are interested in contributing to this repository, please make sure to read the CONTRIBUTING.md and CODE_OF_CONDUCT.md files first.

You can’t perform that action at this time.