From 05d48841adf292bcacb5fef1ede98f3aa31e3adf Mon Sep 17 00:00:00 2001 From: chyyran Date: Sun, 15 Sep 2024 03:00:59 -0400 Subject: [PATCH] doc: update docs for stable build instructions --- README.md | 52 +++++++++++++++++++++------ librashader/src/lib.rs | 80 ++++++++++++++++++++++++------------------ 2 files changed, 87 insertions(+), 45 deletions(-) diff --git a/README.md b/README.md index 6156ca0..2974308 100644 --- a/README.md +++ b/README.md @@ -8,7 +8,7 @@ librashader (*/ˈli:brəʃeɪdɚ/*) is a preprocessor, compiler, and runtime for [![Latest Version](https://img.shields.io/crates/v/librashader.svg)](https://crates.io/crates/librashader) [![Docs](https://docs.rs/librashader/badge.svg)](https://docs.rs/librashader) [![build result](https://build.opensuse.org/projects/home:chyyran:librashader/packages/librashader/badge.svg)](https://software.opensuse.org//download.html?project=home%3Achyyran%3Alibrashader&package=librashader) ![License](https://img.shields.io/crates/l/librashader) -![Nightly rust](https://img.shields.io/badge/rust-nightly-orange.svg) +![Nightly rust](https://img.shields.io/badge/rust-nightly-orange.svg) ![Stable rust](https://img.shields.io/badge/rust-1.77-blue.svg) ## Installation For end-users, librashader is available from the [Open Build Service](https://software.opensuse.org//download.html?project=home%3Achyyran%3Alibrashader&package=librashader) for a variety of Linux distributions and platforms. @@ -92,7 +92,17 @@ static DEFAULT_MVP: &[f32; 16] = &[ As with RetroArch, a rotation on this MVP will be applied only on the final pass for these runtimes. This is the only way to pass orientation information to shaders. -### Building +### Writing a librashader Runtime + +If you wish to contribute a runtime implementation not already available, see the [librashader-runtime](https://docs.rs/librashader-runtime/latest/librashader_runtime/) +crate for helpers and shared logic used across all librashader runtime implementations. Using these helpers and traits will +ensure that your runtime has consistent behaviour for uniform and texture semantics bindings with the existing librashader runtimes. + +These types should not be exposed to the end user in the runtime's public API, and should be kept internal to the implementation of +the runtime. + + +## Building For Rust projects, simply add the crate to your `Cargo.toml`. @@ -112,14 +122,28 @@ This will output a `librashader.dll` or `librashader.so` in the target folder. P While librashader has no build-time dependencies, using `librashader_ld.h` may require headers from the relevant runtime graphics API. -### Writing a librashader Runtime -If you wish to contribute a runtime implementation not already available, see the [librashader-runtime](https://docs.rs/librashader-runtime/latest/librashader_runtime/) -crate for helpers and shared logic used across all librashader runtime implementations. Using these helpers and traits will -ensure that your runtime has consistent behaviour for uniform and texture semantics bindings with the existing librashader runtimes. +### Building against stable Rust +While librashader is intended to be used with nightly Rust until [required features](https://github.com/SnowflakePowered/librashader/issues/55) are stabilized, it supports being +built with stable Rust with the `stable` feature. -These types should not be exposed to the end user in the runtime's public API, and should be kept internal to the implementation of -the runtime. +```toml +librashader = { features = "stable" } +``` + +If building the C API, the `--stable` flag in the build script will enable the `stable` feature. + +``` +cargo +stable run -p librashader-build-script -- --profile optimized --stable +``` + +There are some caveats when building against stable Rust, such that building librashader against nightly Rust is still highly encouraged. + +* C headers will not be regenerated when building with the `stable` feature. +* There is a minor performance hit in initial shader compilation when building against stable Rust. This is due to boxed trait objects being used instead of `impl Trait`. +* A higher MSRV is required when building against stable Rust. + +When the `trait_alias_impl_trait` feature is stabilized, the `stable` feature will be removed. ## Examples @@ -225,12 +249,18 @@ in both the Rust and C API without an increase to either `LIBRASHADER_CURRENT_VE ### MSRV Policy -While librashader requires nightly Rust, the following MSRV policy is enforced for unstable library features. +When building against nightly Rust, the following MSRV policy is enforced for unstable library features. * Windows and macOS: **latest** nightly -* Linux: **1.76** +* Linux: **1.74** -A CI job runs weekly to ensure librashader continues to build on nightly. Note that the MSRV is only intended to ease distribution on Linux and is allowed to change any time. It generally tracks the latest version of Rust available in the latest version of Ubuntu, but this may change with no warning in a patch release. +A CI job runs weekly to ensure librashader continues to build on nightly. + +Building against stable Rust requires a higher MSRV. +* All platforms: **1.77** + +Note that the MSRV is only intended to ease distribution on Linux when building against nightly Rust or with `RUSTC_BOOTSTRAP=1`, and is allowed to change any time. +It generally tracks the latest version of Rust available in the latest version of Ubuntu, but this may change with no warning in a patch release. ## License The core parts of librashader such as the preprocessor, the preset parser, diff --git a/librashader/src/lib.rs b/librashader/src/lib.rs index 027b92a..e022be7 100644 --- a/librashader/src/lib.rs +++ b/librashader/src/lib.rs @@ -104,49 +104,61 @@ pub mod preprocess { #[cfg_attr(feature = "docsrs", doc(cfg(feature = "reflect")))] /// Shader reflection and cross-compilation. /// -/// The `type_alias_impl_trait` nightly feature is required. You should choose your -/// target shading language, and a compilation type. +/// Without the `stable` crate feature, the `type_alias_impl_trait` nightly feature is required. +/// +/// You should choose your target shading language, and a compilation type. /// /// ```rust /// #![feature(type_alias_impl_trait)] +/// mod compile { +/// use std::error::Error; +/// use librashader_preprocess::ShaderSource; +/// use librashader_presets::ShaderPreset; +/// use librashader_reflect::back::{CompileReflectShader, FromCompilation}; +/// use librashader_reflect::back::targets::SPIRV; +/// use librashader_reflect::front::SpirvCompilation; +/// use librashader_reflect::reflect::cross::SpirvCross; +/// use librashader_reflect::reflect::presets::{CompilePresetTarget, ShaderPassArtifact}; +/// use librashader_reflect::reflect::semantics::ShaderSemantics; /// -/// use std::error::Error; -/// use librashader::preprocess::ShaderSource; -/// use librashader::presets::ShaderPreset; -/// use librashader::reflect::{CompileReflectShader, FromCompilation, CompilePresetTarget, ShaderPassArtifact}; -/// use librashader::reflect::targets::SPIRV; -/// use librashader::reflect::semantics::ShaderSemantics; -/// use librashader_reflect::front::{ShaderInputCompiler, SpirvCompilation}; -/// use librashader_reflect::reflect::cross::SpirvCross; -/// type Artifact = impl CompileReflectShader; -/// type ShaderPassMeta = ShaderPassArtifact; +/// type Artifact = impl CompileReflectShader; +/// type ShaderPassMeta = ShaderPassArtifact; /// -/// // Compile single shader -/// pub fn compile_spirv( -/// source: &ShaderSource, -/// ) -> Result> -/// { -/// let compilation = SpirvCompilation::compile(&source)?; -/// let spirv = SPIRV::from_compilation(compilation)?; -/// Ok(spirv) -/// } -/// -/// // Compile preset -/// pub fn compile_preset(preset: ShaderPreset) -> Result<(Vec, ShaderSemantics), Box> -/// { -/// let (passes, semantics) = SPIRV::compile_preset_passes::>( -/// preset.shaders, &preset.textures)?; -/// Ok((passes, semantics)) +/// // Compile preset +/// pub fn compile_preset(preset: ShaderPreset) -> Result<(Vec, ShaderSemantics), Box> +/// { +/// let (passes, semantics) = SPIRV::compile_preset_passes::>( +/// preset.shaders, &preset.textures)?; +/// Ok((passes, semantics)) +/// } /// } /// ``` /// -/// ## What's with all the traits? -/// librashader-reflect is designed to be compiler-agnostic. In the future, we will allow usage of -/// [naga](https://docs.rs/naga/latest/naga/index.html), a pure-Rust shader compiler, when it has -/// matured enough to support [the features librashader needs](https://github.com/gfx-rs/naga/issues/1012). +/// With the `stable` crate feature, a trait object can be used instead. Note the `Send` bound +/// on `Artifact` is required. /// -/// In the meanwhile, the only supported input compiler is [SpirvCompilation](crate::reflect::SpirvCompilation), -/// which does compilation of GLSL to SPIR-V via [glslang](https://github.com/KhronosGroup/glslang/). +/// ``` +/// use librashader_reflect::back::CompileReflectShader; +/// use librashader_reflect::back::targets::SPIRV; +/// use librashader_reflect::front::SpirvCompilation; +/// use librashader_reflect::reflect::cross::SpirvCross; +/// use librashader_reflect::reflect::presets::ShaderPassArtifact; +/// +/// type Artifact = Box + Send>; +/// type ShaderPassMeta = ShaderPassArtifact; +/// ``` +/// +/// ## What's with all the traits? +/// librashader-reflect is designed to be frontend and backend agnostic. +/// +/// Currently [SpirvCompilation](crate::reflect::SpirvCompilation), +/// which does compilation of GLSL to SPIR-V via [glslang](https://github.com/KhronosGroup/glslang/ is the only +/// supported frontend. +/// +/// In the future, we will allow [Naga](https://docs.rs/naga/latest/naga/index.html), a pure-Rust shader compiler, +/// as a frontend, when it has matured enough to support [the features librashader needs](https://github.com/gfx-rs/naga/issues/1012). +/// +/// Both naga and SPIRV-Cross are supported as backends depending on the target. pub mod reflect { /// Supported shader compiler targets. pub mod targets {