Merge pull request #257 from flox/push-xrwxvurpytko

chore: artifact -> package

Author: stahnma

docs/concepts/manifest-builds.md

@@ -1,10 +1,10 @@
 ---
 title: "Builds"
-description: How to use Flox environments to build artifacts 
+description: Understanding how to build packages with Flox
 ---
 
 The typical development lifecycle involves a step where your source code and
-potentially some other assets are bundled together into an artifact.
+potentially some other assets are bundled together into a package.
 That could be a compiled executable, an archive containing source files, or
 something else entirely.
 A Flox environment ensures that the same set of tools, dependencies, and
@@ -17,18 +17,18 @@ during your builds as you do during development.
 
 Builds are defined in the `[build]` section of the manifest.
 Each build specified in the `[build]` section corresponds to a different
-artifact.
-This allows you to produce multiple artifacts from a given set of sources,
+package.
+This allows you to produce multiple packages from a given set of sources,
 for example to produce different versions of a compiled binary both with
 and without debug symbols.
 
 Configuring a build mostly entails providing a short Bash script containing the
-instructions to build the artifact.
+instructions to build the package.
 This script often contains the same commands you would normally run to build
-the artifact in your shell e.g. `make`, `cargo build`, etc.
+the package in your shell e.g. `make`, `cargo build`, etc.
 Flox runs this script inside an activation of the environment so that the tools
 used to develop the software are available during the build.
-The script must also place the artifact into a directory called `$out`,
+The script must also place the package into a directory called `$out`,
 but we'll provide more details on that aspect in just a moment.
 
 An example build definition for a Rust project called `myproject` looks like
@@ -45,7 +45,7 @@ command = '''
 
 As you can see, it's very simple.
 
-### Where to put artifacts
+### Where to put packages
 
 To keep the output of a build separate from the source files,
 every build is supplied with a directory whose path is stored in a variable
@@ -106,10 +106,10 @@ obvious.
 
 At the end of the day, a "build" is just a script that runs in your activated
 environment and places one or more files into a predefined directory.
-Once that build is done, the artifact can be [published][publish-concept] so
+Once that build is done, the package can be [published][publish-concept] so
 that your or anyone else in your organization can install it into their environment.
 This can be a very convenient method of distributing files.
-Sharing artifacts with other users is only possible with an organization.
+Sharing packages with other users is only possible with an organization.
 See the [organizations][organizations-concept] page for more details on organizations.
 
 In short, if you have a file that can be copied into the `$out` directory,
@@ -143,35 +143,35 @@ Say that your organization uses [grpc][grpc] to communicate between services.
 You could vendor the `.proto` files in your project's repository, or store
 the `.proto` files in a separate repository.
 However, you could also write a build that copies these `.proto` files and
-publish the artifact.
+publish the package.
 This allows you to version and attach metadata to the `.proto` files,
-and any team that "installs" the artifact would have access to them.
+and any team that "installs" the package would have access to them.
 
 Furthermore, since these `.proto` files are installed as a package,
 any environment that installs them would be notified when there are updates
 available.
 
 ## Limiting the package size
 
-Your artifact likely has dependencies,
+Your package likely has dependencies,
 and those dependencies have their own dependencies,
 all the way down to `libc`.
 We call this complete set of dependencies the "transitive closure",
-or simply "the closure", of your artifact.
-A large closure for your artifact has no direct impact on runtime performance,
-but it means that your artifact requires more disk space to install and requires
+or simply "the closure", of your package.
+A large closure for your package has no direct impact on runtime performance,
+but it means that your package requires more disk space to install and requires
 more bandwidth to copy from one place to another.
 
 By default all of the packages in the default [package group][pkg-groups] are
-included as dependencies of your artifacts,
-but these packages may only be needed by your artifact at _build_ time or _development_ time,
+included as dependencies of your packages,
+but these packages may only be needed by your package at _build_ time or _development_ time,
 not _run_ time.
 As a reminder, the default package group is called `toplevel`,
 and all packages installed to an environment without an explicit `pkg-group`
 are placed into this package group.
 
 The `runtime-packages` option allows you to trim down the packages from the `toplevel`
-package group that are included as runtime dependencies of your artifact.
+package group that are included as runtime dependencies of your package.
 This option is a list of `install-id`s from the `toplevel` package group.
 As a reminder, the `install-id` is the part of the package descriptor that
 comes before `pkg-path` e.g. `myhello` in `myhello.pkg-path = "hello"`.
@@ -206,7 +206,7 @@ not the name of the package itself (`hello-go`).
 
 The script that you specify in `command` is run on your host machine by default.
 This means that it may build against dependencies that are outside of your
-environment and the artifact may not function correctly when executed or rebuilt
+environment and the package may not function correctly when executed or rebuilt
 on another machine.
 
 In order to improve the reproducibility of your build you can specify that it is
@@ -231,14 +231,14 @@ network.
 ## Cross-platform builds
 
 Currently when you build a package, it is only built for the system (`aarch64-darwin`, `x86_64-linux`, etc) that the build is being run on.
-This means that if you want artifacts built for multiple platforms, you need to run the build on multiple platforms.
+This means that if you want packages built for multiple platforms, you need to run the build on multiple platforms.
 One way to accomplish this is to run your builds in CI.
 
 ## Examples
 
 We've compiled a list of example commands to demonstrate how to use Flox to
-build artifacts in various ecosystems.
-Each language guide in the Languages section of the Cookbook contains an example of building an artifact with Flox.
+build packages in various ecosystems.
+Each language guide in the Languages section of the Cookbook contains an example of building a package with Flox.
 For example, [this section][go-example] contains an example build for the Go language.
 
 [services-concept]: ./services.md

docs/concepts/publishing.md

@@ -1,16 +1,16 @@
 ---
 title: "Publishing"
-description: How to use Flox environments to build artifacts 
+description: Understanding how to publish packages with Flox
 ---
 
-Once you've built an artifact with the [`flox build`][flox-build] command, you likely want to _use_ it somewhere.
-The [`flox publish`][flox-publish] command gives you the ability to upload artifacts to your private catalog so that you can _install_ them into your environments.
+Once you've built a package with the [`flox build`][flox-build] command, you likely want to _use_ it somewhere.
+The [`flox publish`][flox-publish] command gives you the ability to upload packages to your private catalog so that you can _install_ them into your environments.
 In order to share packages with other people you must create an organization.
 See the [organizations][organizations-concept] page for more details.
 
-## Uploading an artifact
+## Uploading a package
 
-The `flox publish <name>` command allows you to upload an artifact built with the `flox build` command, where `<name>` is the name of any build listed in the `build` section of the manifest.
+The `flox publish <name>` command allows you to upload a package built with the `flox build` command, where `<name>` is the name of any build listed in the `build` section of the manifest.
 
 ```toml
 # manifest.toml
@@ -26,44 +26,44 @@ $ flox publish mypkg
 
 ## Publish process
 
-In order to make sure that the uploaded artifact can be built reproducibly,
+In order to make sure that the uploaded package can be built reproducibly,
 Flox imposes some constraints on the build and publish process.
 
 - The Flox environment performing the build must tracked in a git repository.
 - Tracked files in the git repository must be clean.
 - The git repository has a remote defined, and the current revision has been pushed to it.
 - The Flox environment must have at least one package installed to it.
 
-All of this is there to ensure that the published artifact can be locked to a point in time in the Base Catalog and an upstream source revision.
+All of this is there to ensure that the published package can be locked to a point in time in the Base Catalog and an upstream source revision.
 As a reminder, the Base Catalog is the built-in [Catalog][catalog-concept] provided by Flox.
 
 As part of the `flox publish` command, the CLI will clone the git repository to a temporary directory to ensure that any files referenced in the build are tracked by the repository.
 A clean `flox build` is then run in this directory.
 
-If the build completes successfully, the artifact, its closure (all the software it depends on), and its metadata are uploaded to your Catalog.
+If the build completes successfully, the package, its closure (all the software it depends on), and its metadata are uploaded to your Catalog.
 
 ## The published payload
 
-A published artifact consists of two parts:
+A published package consists of two parts:
 
-- The artifact metadata
-- The artifact itself
+- The package metadata
+- The package itself
 
-The artifact metadata is uploaded to Flox servers so that the Flox CLI can see that it's available via the [`flox search`][flox-search], [`flox show`][flox-show], and [`flox install`][flox-install] commands.
-The artifact itself is uploaded to a Catalog Store.
+The package metadata is uploaded to Flox servers so that the Flox CLI can see that it's available via the [`flox search`][flox-search], [`flox show`][flox-show], and [`flox install`][flox-install] commands.
+The package itself is uploaded to a Catalog Store.
 
-A Catalog Store is effectively a cache for published artifacts, and Flox provides one by default.
+A Catalog Store is effectively a cache for published packages, and Flox provides one by default.
 An organization can choose to provide their own Catalog Store in the form of an S3-compatible storage provider.
-In this case, it means that your organization has complete control over your artifacts and they will never be stored by Flox.
+In this case, it means that your organization has complete control over your packages and they will never be stored by Flox.
 To pursue this option, contact Flox directly.
 
-## Consuming published artifacts
+## Consuming published packages
 
-Once you have uploaded an artifact via `flox publish`, the package becomes available in `flox search`, `flox show`, and `flox install`.
+Once you have uploaded a package via `flox publish`, the package becomes available in `flox search`, `flox show`, and `flox install`.
 To distinguish these packages from those provided by the Base Catalog, published packages are prefixed with the name of the user or organization.
-For example, if your user is called `myuser` and you publish an artifact named `hello`, the artifact will appear as `myuser/hello` in the Flox CLI.
+For example, if your user is called `myuser` and you publish a package named `hello`, the package will appear as `myuser/hello` in the Flox CLI.
 
-When a user runs `flox install myuser/hello`, the artifact is downloaded directly from the Catalog Store that it was published to.
+When a user runs `flox install myuser/hello`, the package is downloaded directly from the Catalog Store that it was published to.
 If organizations configure their own Catalog Store (rather than using the default Catalog Store provided by Flox), it is never downloaded to or cached on Flox servers.
 
 ### Sharing

docs/tutorials/build-and-publish.md

@@ -1,6 +1,6 @@
 ---
 title: Build and publish packages
-description: Building and publishing software artifacts with Flox
+description: Building and publishing custom packages with Flox
 ---
 
 # Building with Flox
@@ -86,16 +86,16 @@ Everything appears to be in working order, so now we can discuss what it looks l
 ## Define a build
 
 In order to define a Flox build, we add an entry to the `[build]` section of the manifest.
-Every name added to the `build` section creates a new artifact.
-In our case the artifact will be the compiled Go program, but you can use Flox to build all kinds of things.
+Every name added to the `build` section creates a new package.
+In our case the package will be the compiled Go program, but you can use Flox to build all kinds of things.
 See the [builds][build-concept] page for more examples of what you can build with Flox.
 
 All that's necessary to define a build is a short script that does two things:
 
 - Runs any commands necessary to build the program
 - Copies the program to a directory called `$out`
 
-The `$out` shell variable holds the path to a temporary directory where your build artifact should be placed (again, "artifact" in our case means the compiled `hello` program).
+The `$out` shell variable holds the path to a temporary directory where your build package should be placed (again, "package" in our case means the compiled `hello` program).
 The `$out` directory adheres to the [Filesystem Hierarchy Standard (FHS)][fhs], which is just the formal name for the convention of placing executable files in `/bin`, libraries in `/lib`, etc.
 For this `hello` program we'll want to place it in `$out/bin` since `hello` is an executable program, and that's where the FHS says to put those types of files.
 Flox expects you to put executables there, and if you put them somewhere else you may experience unexpected behavior.
@@ -186,18 +186,18 @@ Completed build of hello-opt-unknown in local mode
 ✨ Build completed successfully. Output created: ./result-hello-opt
 ```
 
-## Publish the artifact
+## Publish the package
 
 --8<-- "paid-feature.md"
 
-Now that the artifact is built, we can send it somewhere.
-Every user has a private catalog that they can publish artifacts to.
+Now that the package is built, we can send it somewhere.
+Every user has a private catalog that they can publish packages to.
 In order to share packages with other people you must create an organization.
 This is a paid feature, and if you would like access to it you should contact Flox directly.
 See the [organizations][organizations-concept] page for more details.
 
-Now that you've built the artifact you can [publish][publish-concept] it to your private catalog via the `flox publish` command.
-This command has a few requirements to make sure that the artifact you're publishing can be built by other people reproducibly:
+Now that you've built the package you can [publish][publish-concept] it to your private catalog via the `flox publish` command.
+This command has a few requirements to make sure that the package you're publishing can be built by other people reproducibly:
 
 - The Flox environment must be in a git repository.
 - All tracked files in the repository must be clean.
@@ -211,16 +211,16 @@ Let's say that we've done all of that so that we can publish our `hello` program
 flox [myproject] $ flox publish hello
 ```
 
-The `flox publish` command performs a clean build of the artifact in a temporary directory to ensure that the build doesn't depend on anything outside of the git repository.
+The `flox publish` command performs a clean build of the package in a temporary directory to ensure that the build doesn't depend on anything outside of the git repository.
 
-In order to upload an artifact during the publish process (and not just upload metadata), you must provide a signing key via the `--signing-private-key` option.
-Attempting to upload an artifact without a signing key is an error because other users would not be able to install the artifact.
+In order to upload a package during the publish process (and not just upload metadata), you must provide a signing key via the `--signing-private-key` option.
+Attempting to upload a package without a signing key is an error because other users would not be able to install the package.
 
-## Install the artifact
+## Install the package
 
-Now that you've published the artifact, it will show up in [`flox search`][flox-search] and [`flox show`][flox-show], and can be installed via [`flox install`][flox-install].
+Now that you've published the package, it will show up in [`flox search`][flox-search] and [`flox show`][flox-show], and can be installed via [`flox install`][flox-install].
 The package will appear with your username or organization name prefixed to the package name.
-Let's say your username is `myuser` and the package name is `hello`, in which case the published artifact will appear as `myuser/hello` in `flox show`, `flox search`, and `flox install`.
+Let's say your username is `myuser` and the package name is `hello`, in which case the published package will appear as `myuser/hello` in `flox show`, `flox search`, and `flox install`.
 Let's see that in action with `flox search`:
 
 ```text