From e5f96e832b60e6515255d1a06efa4a75a54ebc1b Mon Sep 17 00:00:00 2001 From: Ryan Lambert Date: Tue, 21 Mar 2023 07:42:36 -0600 Subject: [PATCH] Removing content from README that is now in main documentation (#266) --- README.md | 78 +++++++------------------------------------- doc/src/SUMMARY.md | 13 +++++--- doc/src/config-pg.md | 3 +- doc/src/config.md | 7 ---- doc/src/plrust.md | 8 ++--- 5 files changed, 26 insertions(+), 83 deletions(-) delete mode 100644 doc/src/config.md diff --git a/README.md b/README.md index 959b6c2e..995f1558 100644 --- a/README.md +++ b/README.md @@ -7,6 +7,8 @@ are not interpreted. The top advantages of PL/Rust include writing natively-compiled functions to achieve the absolute best performance, access to Rust's large development ecosystem, and Rust's compile-time safety guarantees. +> The PL/Rust [documentation is moving](https://tcdi.github.io/plrust/) to a more user friendly format. The mdbook format documentation is auto-generated from the main branch. + PL/Rust provides access to Postgres' Server Programming Interface (SPI) including dynamic queries, prepared statements, and cursors. It also provides safe Rust types over most of Postgres built-in data types, including (but not limited to), TEXT, INT, BIGINT, NUMERIC, FLOAT, DOUBLE PRECISION, DATE, TIME, etc. @@ -215,30 +217,13 @@ you can omit the `--features "trusted"` arguments. # Configuration -PL/Rust has a few required configuration options, but first and foremost it **must** be configured as a -`shared_preload_libraries` entry in `postgresql.conf`. For example: - -``` -shared_preload_libraries = 'plrust' -``` +See the [PostgreSQL Configuration](https://tcdi.github.io/plrust/config-pg.html) +section of the documentation for notes on configuring PL/Rust in +`postgresql.conf`. -Failure to do so will cause the plrust extension to raise an ERROR whenever Postgres tries to first load it. -The PL/Rust-specific configuration options, some of which are **required**, are: +---- -| Option | Type | Description | Required | Default | -|------------------------------------|--------|---------------------------------------------------------------------------------------------------------------------------------------------------------------|----------|----------------------------------------------------------------------------------------------------------------------| -| `plrust.work_dir` | string | The directory where pl/rust will build functions with cargo. | yes | | -| `plrust.PATH_override` | string | If `cargo` and `cc` aren't in the `postmaster`'s `$PATH`, set this. | no | environment or `~/.cargo/bin:/usr/bin` if `$PATH` is unset | -| `plrust.tracing_level` | string | A [tracing directive][docs-rs-tracing-directive]. | no | `'info'` | -| `plrust.compilation_targets` | string | Comma separated list of CPU targets (x86_64, aarch64). | no | | -| `plrust.x86_64_linker` | string | Name of the linker `rustc` should use on fo cross-compile. | no | `'x86_64_linux_gnu_gcc'` | -| `plrust.aarch64_linker` | string | Name of the linker `rustc` should use on for cross-compile. | no | `'aarch64_linux_gnu_gcc'` | -| `plrust.x86_64_pgx_bindings_path` | string | Path to output from `cargo pgx cross pgx-target` on x86_64. | no-ish | | -| `plrust.aarch64_pgx_bindings_path` | string | Path to output form `cargo pgx cross pgx-target` on aarch64. | no-ish | | -| `plrust.compile_lints` | string | A comma-separated list of Rust lints to apply to every user function. | no | `'plrust_extern_blocks, plrust_lifetime_parameterized_traits, implied_bounds_entailment, unsafe_code, plrust_filesystem_macros, plrust_env_macros, plrust_external_mod, plrust_fn_pointers, plrust_async, plrust_leaky, plrust_print_macros, plrust_stdio, unknown_lints, deprecated, suspicious_auto_trait_impls, unaligned_references, soft_unstable, plrust_autotrait_impls'` | -| `plrust.required_lints` | string | A comma-separated list of Rust lints that are required to have been applied to a user function before PL/Rust will load the library and execute the function. | no | defaults to whatever `plrust.compile_lints` happens to be | -| `plrust.trusted_pgx_version` | string | The version of the [`plrust-trusted-pgx`](https://crates.io/crates/plrust-trusted-pgx) crate from crates.io to use when compiling user functions | For PL/Rust to cross compile user functions it needs to know which CPU architectures via `plrust.compilation_targets`. This is a comma-separated list of values, of which only `x86_64` and `aarch64` are @@ -261,55 +246,16 @@ the other architecture. ### Lints -As discussed above, PL/Rust has its own "rustc driver" named `plrustc`. This must be installed using the -[`plrustc/build.sh`](plrustc/build.sh) script and the resulting executable must be on the `PATH`, or it should reside -somewhere that is included in the `plrust.PATH_override` GUC. +See the [Lints section](https://tcdi.github.io/plrust/config-lints.html) +of the documentation. -The `plrust.required_lints` GUC defines which lints must have been applied to a function before PL/Rust will load the -library and execute the function. Using the `PLRUST_REQUIRED_LINTS` environment variable, it is possible to enforce -that certain lints are always required of compiled functions, regardless of the `plrust.required_lints` GUC value. -`PLRUST_REQUIRED_LINTS`'s format is a comma-separated list of lint named. It must be set in the environment in which -Postgres is started. The intention here is that the system administrator can force certain lints for execution if for -some reason `postgresql.conf` or the users able to modify it are not trusted. ## Environment Variables -As part of PL/Rust's function compilation machinery, and in conjunction with `pgx` which does the hard work, a number -of environment variables are set when PL/Rust executes `cargo`. - -These are not environment variables that need to set manually. Generally, these are auto-detected and cannot be -overridden through configuration. - -| Name | Value | How it's Used | -|---------------------------------------------|-------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| PATH | `~/cargo/bin:/usr/bin` or `/usr/bin` if "postgres" user has no home directory | The `PATH` environment variable is **only** set by PL/Rust if it detects that one isn't already set.
As mentioned above, this one *can* be overridden via the `plrust.PATH_override` GUC in `postgresql.conf`. | -| RUSTC | `plrustc` | This is set to plrust's "rust driver" executable, named `plrustc`. It must be on the system PATH. | -| RUSTFLAGS | `"-Clink-args=-Wl,-undefined,dynamic_lookup"` | Used by `rustc` to indicate that Postgres internal symbols are only available at run-time, not compile-time. | -| CARGO_TARGET_DIR | value of GUC `plrust.work_dir`/`target` | This is the filesystem path `cargo` will store its intermediate compilation artifacts. | - | CARGO_TARGET_X86_64_LINKER | `x86_64-linux-gnu-gcc` | Used only when cross-compiling *to* x86_64, this tells `rustc` which linker to use. The `plrust.x86_64_linker` GUC can override the default. | -| CARGO_TARGET_AARCH64_LINKER | `aarch64-linux-gnu-gcc` | Used only when cross-compiling *to* aarch64, this tells `rustc` which linker to use. The `plrust.aarch64_linker` GUC can override the default. | - | PGX_TARGET_INFO_PATH_PG${MAJOR_VERSION_NUM} | unset unless `plrust.{x86_64/aarch64}_pgx_bindings_path` GUC is set | Used only when cross-compiling *to* the specified target. This tells `pgx` where to find the generated Postgres bindings for that platform. | -| PGX_PG_CONFIG_AS_EN_VAR | `true` | Indicates to the `plrust-trusted-pgx` dependency, and ultimately `pgx` itself that instead of getting the values it needs for compilation from the Postgres `pg_config` tool, it should get them from environment variables. | -| PGX_PG_CONFIG_VERSION | Provided by the running Postgres instance | Used by `pgx` to build the PL/Rust user function. | -| PGX_PG_CONFIG_CPPFLAGS | Provided by the running Postgres instance | Used by `pgx` to build the PL/Rust user function (technically unused by PL/Rust's build process as PL/Rust does not include the pgx "cshim" for which this is normally used). | -| PGX_PG_CONFIG_INCLUDEDIR-SERVER | Provided by the running Postgres instance | Used by `pgx` to build the PL/Rust user function. | -| PLRUSTC_USER_CRATE_NAME | The name of the user crate | Used by `plrust` to help `plrustc` distinguish between the PL/Rust user function and dependencies. | -| PLRUSTC_USER_CRATE_ALLOWED_SOURCE_PATHS | The user crate dir and the cargo target dir, separated by `:`. | When compiling the user crate (given by `PLRUSTC_USER_CRATE_NAME`), `plrustc` ensures no source files outside of these (`:`-delimited) directories are accessed. Every path in the list should be absolute and have symlinks resolved. The sysroot is currently automatically added to this list. | - -There are a number of other `pg_config`-related environment variables that plrust sets. These are not currently used, -but are reserved for future use, should they become necessary to build a user function: -`PGX_PG_CONFIG_BINDIR, PGX_PG_CONFIG_DOCDIR, PGX_PG_CONFIG_HTMLDIR, PGX_PG_CONFIG_INCLUDEDIR, PGX_PG_CONFIG_PKGINCLUDEDIR, PGX_PG_CONFIG_INCLUDEDIR-SERVER, PGX_PG_CONFIG_LIBDIR, PGX_PG_CONFIG_PKGLIBDIR, PGX_PG_CONFIG_LOCALEDIR, PGX_PG_CONFIG_MANDIR, PGX_PG_CONFIG_SHAREDIR, PGX_PG_CONFIG_SYSCONFDIR, PGX_PG_CONFIG_PGXS, PGX_PG_CONFIG_CONFIGURE, PGX_PG_CONFIG_CC, PGX_PG_CONFIG_CPPFLAGS, PGX_PG_CONFIG_CFLAGS, PGX_PG_CONFIG_CFLAGS_SL, PGX_PG_CONFIG_LDFLAGS, PGX_PG_CONFIG_LDFLAGS_EX, PGX_PG_CONFIG_LDFLAGS_SL, PGX_PG_CONFIG_LIBS, PGX_PG_CONFIG_VERSION` - -Note that PL/Rust uses Rust's [`std::process::Command`](https://doc.rust-lang.org/beta/std/process/struct.Command.html) -to exec `cargo`. As such, it **will** inherit **all** environment variables set under the active backend `postgres` -process. We recommend Postgres' execution environment be properly sanitized to your organizations requirements. - -As a pre-emptive measure, PL/Rust proactively unsets a few environment variables that could negatively impact user function -compilation: - `DOCS_RS, PGX_BUILD_VERBOSE, PGX_PG_SYS_GENERATE_BINDINGS_FOR_RELEASE, CARGO_MANIFEST_DIR, OUT_DIR, RUSTC_WRAPPER, RUSTC_WORKSPACE_WRAPPER` -(These are generally things used by the `pgx` development team and not at all necessary for PL/Rust.) - -`plrustc` also performs a search for the location of the Rust sysroot which is informed by several environment variables (specifically `PLRUSTC_SYSROOT`, `SYSROOT`, `RUSTUP_TOOLCHAIN`, and `RUSTUP_HOME`). The details of how this search is performed are documented in the ([`plrustc` README](./plrustc/README.md)), but it is very similar to the search performed by `clippy`, `miri`, and other tools that use the `rustc_driver` library. +See the [Environment variables section](https://tcdi.github.io/plrust/config-env-var.html) +of the documentation. + + # Quickly Getting Started diff --git a/doc/src/SUMMARY.md b/doc/src/SUMMARY.md index 3248f870..55df5b02 100644 --- a/doc/src/SUMMARY.md +++ b/doc/src/SUMMARY.md @@ -8,7 +8,7 @@ - [Update PL/Rust](./update-plrust.md) - [Cross compilation](./install-cross-compile.md) -# User Guide +# PL/Rust Usage - [PL/Rust Functions and Arguments](./use-plrust.md) - [Data types](./data-types.md) @@ -16,13 +16,16 @@ - [Logging to PostgreSQL from PL/Rust](./logging.md) - [Triggers](./triggers.md) - [SPI](./spi.md) -- [Configuration](./config.md) - - [PostgreSQL configuration](./config-pg.md) - - [Lints](./config-lints.md) - - [Environment variables](./config-env-var.md) - [Trusted and Untrusted PL/Rust](./trusted-untrusted.md) - [Rules and Regulations](./rules-regulations.md) +# PL/Rust Configuration + +- [PostgreSQL configuration](./config-pg.md) +- [Lints](./config-lints.md) +- [Environment variables](./config-env-var.md) + + # PL/Rust Under the Hood diff --git a/doc/src/config-pg.md b/doc/src/config-pg.md index 783285ce..270f7e8b 100644 --- a/doc/src/config-pg.md +++ b/doc/src/config-pg.md @@ -25,8 +25,9 @@ The PL/Rust-specific configuration options are in the following table. | `plrust.aarch64_linker` | string | Name of the linker `rustc` should use on for cross-compile. | no | `'aarch64_linux_gnu_gcc'` | | `plrust.x86_64_pgx_bindings_path` | string | Path to output from `cargo pgx cross pgx-target` on x86_64. | no-ish | | | `plrust.aarch64_pgx_bindings_path` | string | Path to output form `cargo pgx cross pgx-target` on aarch64. | no-ish | | -| `plrust.compile_lints` | string | A comma-separated list of Rust lints to apply to every user function. | no | `'plrust_extern_blocks, plrust_lifetime_parameterized_traits, implied_bounds_entailment, unsafe_code, plrust_filesystem_macros, plrust_fn_pointers, plrust_async, unknown_lints' | +| `plrust.compile_lints` | string | A comma-separated list of Rust lints to apply to every user function. | no | `'plrust_extern_blocks, plrust_lifetime_parameterized_traits, implied_bounds_entailment, unsafe_code, plrust_filesystem_macros, plrust_env_macros, plrust_external_mod, plrust_fn_pointers, plrust_async, plrust_leaky, plrust_print_macros, plrust_stdio, unknown_lints, deprecated, suspicious_auto_trait_impls, unaligned_references, soft_unstable, plrust_autotrait_impls'` | | `plrust.required_lints` | string | A comma-separated list of Rust lints that are required to have been applied to a user function before PL/Rust will load the library and execute the function. | no | defaults to whatever `plrust.compile_lints` happens to be | +| `plrust.trusted_pgx_version` | string | The version of the [`plrust-trusted-pgx`](https://crates.io/crates/plrust-trusted-pgx) crate from crates.io to use when compiling user functions | For PL/Rust to cross compile user functions it needs to know which CPU architectures via `plrust.compilation_targets`. This is a comma-separated list of values, of which only `x86_64` and `aarch64` are diff --git a/doc/src/config.md b/doc/src/config.md deleted file mode 100644 index 41e259f4..00000000 --- a/doc/src/config.md +++ /dev/null @@ -1,7 +0,0 @@ -# Configuration - -PL/Rust has multiple types of configuration. - -- [PostgreSQL configuration](./config-pg.md) -- [Lints](./config-lints.md) -- [Environment variables](./config-env-var.md) diff --git a/doc/src/plrust.md b/doc/src/plrust.md index ab2e6ae2..3f9b35ad 100644 --- a/doc/src/plrust.md +++ b/doc/src/plrust.md @@ -55,8 +55,8 @@ SELECT strlen('Hello, PL/Rust'); ## Built on pgx -PL/Rust is built on the `pgx` framework. Documentation on the pgx crate is -[found here](https://docs.rs/pgx/latest/pgx/). - - +PL/Rust itself is a [`pgx`](https://github.com/tcdi/pgx)-based Postgres extension. Furthermore, each `LANGUAGE +plrust` function are themselves mini-pgx extensions. `pgx`is a generalized framework for developing Postgres extensions with Rust. Like this project, `pgx` +is developed by [TCDI](https://www.tcdi.com). +The following sections discuss PL/Rusts safety guarantees, configuration settings, and installation instructions.