diff --git a/CARGO_README.md b/CARGO_README.md new file mode 100644 index 0000000000..f1205f2cf2 --- /dev/null +++ b/CARGO_README.md @@ -0,0 +1,71 @@ +# The Tectonic Typesetting System + +The `tectonic` crate delivers a modernized, complete, self-contained +[TeX](https://en.wikipedia.org/wiki/TeX)/[LaTeX](https://www.latex-project.org/) +engine, powered by [XeTeX](http://xetex.sourceforge.net/) and +[TeXLive](https://www.tug.org/texlive/). It provides a CLI and ties together the +functionality of a large collection of sub-crates. + +- [User Website](https://tectonic-typesetting.github.io/) +- [The Tectonic Book](https://tectonic-typesetting.github.io/book/latest/) +- [Installation](https://tectonic-typesetting.github.io/book/latest/installation/) of the CLI +- [Detailed Build Instructions][build-inst] +- [API Documentation](https://docs.rs/tectonic/) +- [Issues](https://github.com/tectonic-typesetting/tectonic/issues/) +- [Changelog](https://github.com/tectonic-typesetting/tectonic/blob/release/CHANGELOG.md) + +[build-inst]: https://tectonic-typesetting.github.io/book/latest/howto/build-tectonic/ + + +## Building Tectonic + +The Tectonic crates collectively depend on a relatively large number of +third-party libraries. See [the Book’s build instructions][build-inst] for a +listing and guidance on setting up the build. + +The crate build can be customized with the following [Cargo features]: + +[Cargo features]: https://doc.rust-lang.org/cargo/reference/features.html + +- `external-harfbuzz`: build against an external version of the [Harfbuzz] text + shaping library, rather than a vendored version (the default) +- `geturl-curl`: use the [curl] crate to implement HTTP requests. In order for + this to take effect, you must use `--no-default-features` because + `geturl-reqwest` is a default feature and it takes precedence +- `geturl-reqwest`: use the [reqwest] crate to implement HTTP requests (enabled + by default) +- `native-tls-vendored`: if using [reqwest], activate the `vendored` option in + the [native-tls] crate, causing OpenSSL to be vendored + +[Harfbuzz]: https://harfbuzz.github.io/ +[curl]: https://docs.rs/curl/ +[reqwest]: https://docs.rs/reqwest/ +[native-tls]: https://github.com/sfackler/rust-native-tls + +[The Book][build-inst] describes some less-used features and provides a bit more +detail. + + +## Sub-crates + +The main `tectonic` crate ties together the functionality of a number of +sub-crates: + +- [`tectonic_bridge_core`](https://crates.io/crates/tectonic_bridge_core) +- [`tectonic_bridge_flate`](https://crates.io/crates/tectonic_bridge_flate) +- [`tectonic_bridge_freetype2`](https://crates.io/crates/tectonic_bridge_freetype2) +- [`tectonic_bridge_graphite2`](https://crates.io/crates/tectonic_bridge_graphite2) +- [`tectonic_bridge_harfbuzz`](https://crates.io/crates/tectonic_bridge_harfbuzz) +- [`tectonic_bridge_icu`](https://crates.io/crates/tectonic_bridge_icu) +- [`tectonic_cfg_support`](https://crates.io/crates/tectonic_cfg_support) +- [`tectonic_dep_support`](https://crates.io/crates/tectonic_dep_support) +- [`tectonic_engine_bibtex`](https://crates.io/crates/tectonic_engine_bibtex) +- [`tectonic_engine_xdvipdfmx`](https://crates.io/crates/tectonic_engine_xdvipdfmx) +- [`tectonic_engine_xetex`](https://crates.io/crates/tectonic_engine_xetex) +- [`tectonic_errors`](https://crates.io/crates/tectonic_errors) +- [`tectonic_geturl`](https://crates.io/crates/tectonic_geturl) +- [`tectonic_io_base`](https://crates.io/crates/tectonic_io_base) +- [`tectonic_pdf_io`](https://crates.io/crates/tectonic_pdf_io) +- [`tectonic_status_base`](https://crates.io/crates/tectonic_status_base) +- [`tectonic_xdv`](https://crates.io/crates/tectonic_xdv) +- [`tectonic_xetex_layout`](https://crates.io/crates/tectonic_xetex_layout) diff --git a/Cargo.toml b/Cargo.toml index 02719b2209..dd3aea3431 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -14,7 +14,7 @@ of support files. homepage = "https://tectonic-typesetting.github.io/" documentation = "https://docs.rs/tectonic" repository = "https://github.com/tectonic-typesetting/tectonic/" -readme = "README.md" +readme = "CARGO_README.md" keywords = ["tex", "latex", "typesetting", "font"] categories = ["command-line-interface", "parser-implementations", "rendering", "science", "text-processing"] license = "MIT" diff --git a/README.md b/README.md index d58be0902b..417a4d8234 100644 --- a/README.md +++ b/README.md @@ -11,9 +11,13 @@ engine, powered by [XeTeX](http://xetex.sourceforge.net/) and ## Read this first -If you just want to compile TeX documents, you should probably **click through to -[the main Tectonic website](https://tectonic-typesetting.github.io/)**. This -page is primarily aimed at folks interested in how Tectonic works “under the hood.” +If you just want to compile TeX documents, you should probably **click through +to [the main Tectonic website](https://tectonic-typesetting.github.io/)**. This +page is primarily aimed at folks interested in how Tectonic works “under the +hood.” If you want to build the [`tectonic`][crate] Rust crate, check out [its +README](./CARGO_README.md). + +[crate]: https://crates.io/crates/tectonic ## Developer dashboard @@ -21,13 +25,13 @@ page is primarily aimed at folks interested in how Tectonic works “under the h Packaging status -- [User website](https://tectonic-typesetting.github.io/). -- [Community discussion forum](https://tectonic.newton.cx/). -- [Installation](https://tectonic-typesetting.github.io/install.html). -- [Developer documentation, including build instructions](https://tectonic-typesetting.github.io/develop.html). -- [API documentation](https://docs.rs/tectonic/). -- [Issues](https://github.com/tectonic-typesetting/tectonic/issues/). -- [Changelog](./CHANGELOG.md). +- [User website](https://tectonic-typesetting.github.io/) +- [Community discussion forum](https://tectonic.newton.cx/) +- [Installation](https://tectonic-typesetting.github.io/book/latest/installation/) +- [Build instructions](https://tectonic-typesetting.github.io/book/latest/howto/build-tectonic/) +- [API documentation](https://docs.rs/tectonic/) +- [Issues](https://github.com/tectonic-typesetting/tectonic/issues/) +- [Changelog](https://github.com/tectonic-typesetting/tectonic/blob/release/CHANGELOG.md) ## Technical ecosystem @@ -67,60 +71,3 @@ any given time. Please see [the tectonic-staging README](https://github.com/tectonic-typesetting/tectonic-staging#readme) for more information. (Or at least, more words on the topic.) - - -## Cargo Features - -The Tectonic build can be customized with the following [Cargo features]: - -[Cargo features]: https://doc.rust-lang.org/cargo/reference/features.html - -##### `external-harfbuzz` - -By default, the Tectonic crates will build and link to a “vendored” (static, -internal) version of the [Harfbuzz] text shaping library. If you would like to -link to an externally-supplied version instead, enable this feature. The -external library can be detected with either [pkg-config] or [vcpkg]. See the -[How To Build Tectonic][howto-build] guide for more details. - -[Harfbuzz]: https://harfbuzz.github.io/ -[pkg-config]: https://www.freedesktop.org/wiki/Software/pkg-config/ -[vcpkg]: https://vcpkg.readthedocs.io/ -[howto-build]: https://tectonic-typesetting.github.io/book/latest/#update-link-when-published - -##### `geturl-curl` - -Use the [curl] crate to implement HTTP requests. In order for this to take -effect, you must use `--no-default-features` because `geturl-reqwest` is a -default feature and it takes precedence. - -[curl]: https://docs.rs/curl/ - -##### `geturl-reqwest` (enabled by default) - -Use the [reqwest] crate to implement HTTP requests. This is the default -selection. - -[reqwest]: https://docs.rs/reqwest/ - -##### `native-tls-vendored` - -If using [reqwest], activate the `vendored` option in the [native-tls] crate, -causing OpenSSL to be vendored. This can be useful when cross-compiling or -building static binaries, but is discouraged because that means that the -resulting binaries won't benefit from security fixes to system TLS libraries. - -[native-tls]: https://github.com/sfackler/rust-native-tls - -##### `serialization` (enabled by default) - -This feature enables (de)serialization using the [serde](https://serde.rs/) -crate. At the moment, this is only used to read per-user configuration from a -[TOML](https://github.com/toml-lang/toml) file. If this feature is disabled, the -per-user configuration file will be silently ignored. This feature is provided -because serialization requires the `serde_derive` crate, which in turn uses -Rust’s `proc_macro` feature. The `proc_macro` functionality is difficult to -build with statically linked targets, although Tectonic’s CI system -[demonstrates how to make it work][static-proc-macro]. - -[static-proc-macro]: https://github.com/tectonic-typesetting/tectonic-ci-support/tree/master/cross-images#readme diff --git a/docs/src/getting-started/install.md b/docs/src/getting-started/install.md index 849c77ceab..628bf71cb4 100644 --- a/docs/src/getting-started/install.md +++ b/docs/src/getting-started/install.md @@ -26,7 +26,7 @@ you should: 4. Put that file in the appropriate location so that you can easily run it from your computer’s command prompt. -[gh-latest]: https://github.com/tectonic-typesetting/tectonic/releases/latest +[gh-latest]: https://tectonic-typesetting.github.io/latest.html [inst-packaged]: ../installation/index.md#pre-built-binary-packages [inst-ref]: ../installation/index.md diff --git a/docs/src/installation/index.md b/docs/src/installation/index.md index 1930a6bd8b..951631239d 100644 --- a/docs/src/installation/index.md +++ b/docs/src/installation/index.md @@ -30,7 +30,7 @@ release is published with precompiled executables attached. Because Tectonic is distributed as a single executable, all you need to do is download the appropriate archive for your platform and unpack it. -[gh-latest]: https://github.com/tectonic-typesetting/tectonic/releases/latest +[gh-latest]: https://tectonic-typesetting.github.io/latest.html For instance, on most Linux systems, you’ll want to download the file with the name looking like `tectonic--x86_64-unknown-linux-gnu.tar.gz`. This @@ -68,14 +68,14 @@ complete, the command `conda` will now be available in your terminal. Once the `conda` command is available, you can install Tectonic and its support libraries using [conda-forge](http://conda-forge.github.io/), a community-led -Conda packaing project. To install Tectonic you must activate conda-forge, which -can be done temporarily like so: +Conda packaging project. To install Tectonic you must activate conda-forge, +which can be done temporarily like so: ```sh -conda install -c conda-forge tectonic +$ conda install -c conda-forge tectonic ``` -### Pre-built packages for Arch Linux +### Arch Linux For users of [Arch Linux], there are two Tectonic packages available. The [tectonic-bin][arch-tectonic-bin] package on [AUR] provides actual pre-compiled @@ -87,6 +87,60 @@ machine, which may take a while. [AUR]: https://aur.archlinux.org/ [arch-tectonic]: https://aur.archlinux.org/packages/tectonic/ +### Homebrew + +There is a `tectonic` package in [Homebrew](https://brew.sh/). If you already +have Homebrew installed, installing Tectonic should be as simple as: + +```sh +$ brew install tectonic +``` + +We also have instructions about [installing Tectonic’s dependencies using +Homebrew][homebrew-deps] if you’d like to compile Tectonic yourself on your +Homebrew-based computer. + +[homebrew-deps]: /howto/build-tectonic/external-dep-install.md#homebrew-on-macos + +### MacPorts + +There is a `tectonic` port in [MacPorts](https://www.macports.org/). If you +already have MacPorts installed, installing Tectonic should be as simple as: + +```sh +$ sudo port install tectonic +``` + +### nix or nixOS + +If you're using [nix], you can imperatively install [`tectonic`][nix-tectonic] with: + +```sh +$ nix-env -iA nixos.tectonic +``` + +in your shell. You can also create a temporary environment using +[`nix-shell`](https://nixos.org/nix/manual/#sec-nix-shell): + +```sh +$ nix-shell '' -A tectonic +``` + +[nix]: https://nixos.org/ +[nix-tectonic]: https://nixos.org/nixos/packages.html#tectonic + +### Void Linux + +Void Linux has a `tectonic` package in the [void-packages] repository. To +install it, run: + +```sh +$ sudo xbps-install -S tectonic +``` + +[void-packages]: https://github.com/void-linux/void-packages/blob/master/srcpkgs/tectonic/template + + ## Compile Tectonic Yourself @@ -94,7 +148,7 @@ You can always compile Tectonic yourself. If your system has C++ and Rust compilers installed, this may be as simple as running: ```sh -cargo install tectonic +$ cargo install tectonic ``` However, Tectonic requires various C/C++ support libraries that may not be