diff options
Diffstat (limited to 'doc')
-rw-r--r-- | doc/languages-frameworks/beam.section.md | 2 | ||||
-rw-r--r-- | doc/languages-frameworks/php.section.md | 140 | ||||
-rw-r--r-- | doc/languages-frameworks/python.section.md | 4 | ||||
-rw-r--r-- | doc/languages-frameworks/ruby.section.md | 3 | ||||
-rw-r--r-- | doc/preface.chapter.md | 2 | ||||
-rw-r--r-- | doc/stdenv/meta.chapter.md | 5 | ||||
-rw-r--r-- | doc/stdenv/stdenv.chapter.md | 22 | ||||
-rw-r--r-- | doc/using/overlays.chapter.md | 2 |
8 files changed, 171 insertions, 9 deletions
diff --git a/doc/languages-frameworks/beam.section.md b/doc/languages-frameworks/beam.section.md index 4c1650781f053..5e85723085c12 100644 --- a/doc/languages-frameworks/beam.section.md +++ b/doc/languages-frameworks/beam.section.md @@ -154,7 +154,7 @@ Here is how your `default.nix` file would look for a phoenix project. with import <nixpkgs> { }; let - # beam.interpreters.erlang_23 is available if you need a particular version + # beam.interpreters.erlang_26 is available if you need a particular version packages = beam.packagesWith beam.interpreters.erlang; pname = "your_project"; diff --git a/doc/languages-frameworks/php.section.md b/doc/languages-frameworks/php.section.md index 6c4315f5c4876..2ca55aef1eff9 100644 --- a/doc/languages-frameworks/php.section.md +++ b/doc/languages-frameworks/php.section.md @@ -130,6 +130,7 @@ package: a project may depend on certain extensions and `composer` won't work with that project unless those extensions are loaded. Example of building `composer` with additional extensions: + ```nix (php.withExtensions ({ all, enabled }: enabled ++ (with all; [ imagick redis ])) @@ -138,7 +139,9 @@ Example of building `composer` with additional extensions: ### Overriding PHP packages {#ssec-php-user-guide-overriding-packages} -`php-packages.nix` form a scope, allowing us to override the packages defined within. For example, to apply a patch to a `mysqlnd` extension, you can simply pass an overlay-style function to `php`’s `packageOverrides` argument: +`php-packages.nix` form a scope, allowing us to override the packages defined +within. For example, to apply a patch to a `mysqlnd` extension, you can simply +pass an overlay-style function to `php`’s `packageOverrides` argument: ```nix php.override { @@ -153,3 +156,138 @@ php.override { }; } ``` + +### Building PHP projects {#ssec-building-php-projects} + +With [Composer](https://getcomposer.org/), you can effectively build PHP +projects by streamlining dependency management. As the de-facto standard +dependency manager for PHP, Composer enables you to declare and manage the +libraries your project relies on, ensuring a more organized and efficient +development process. + +Composer is not a package manager in the same sense as `Yum` or `Apt` are. Yes, +it deals with "packages" or libraries, but it manages them on a per-project +basis, installing them in a directory (e.g. `vendor`) inside your project. By +default, it does not install anything globally. This idea is not new and +Composer is strongly inspired by node's `npm` and ruby's `bundler`. + +Currently, there is no other PHP tool that offers the same functionality as +Composer. Consequently, incorporating a helper in Nix to facilitate building +such applications is a logical choice. + +In a Composer project, dependencies are defined in a `composer.json` file, +while their specific versions are locked in a `composer.lock` file. Some +Composer-based projects opt to include this `composer.lock` file in their source +code, while others choose not to. + +In Nix, there are multiple approaches to building a Composer-based project. + +One such method is the `php.buildComposerProject` helper function, which serves +as a wrapper around `mkDerivation`. + +Using this function, you can build a PHP project that includes both a +`composer.json` and `composer.lock` file. If the project specifies binaries +using the `bin` attribute in `composer.json`, these binaries will be +automatically linked and made accessible in the derivation. In this context, +"binaries" refer to PHP scripts that are intended to be executable. + +To use the helper effectively, simply add the `vendorHash` attribute, which +enables the wrapper to handle the heavy lifting. + +Internally, the helper operates in three stages: + +1. It constructs a `composerRepository` attribute derivation by creating a + composer repository on the filesystem containing dependencies specified in + `composer.json`. This process uses the function + `php.mkComposerRepository` which in turn uses the + `php.composerHooks.composerRepositoryHook` hook. Internaly this function uses + a custom + [Composer plugin](https://github.com/nix-community/composer-local-repo-plugin) to + generate the repository. +2. The resulting `composerRepository` derivation is then used by the + `php.composerHooks.composerInstallHook` hook, which is responsible for + creating the final `vendor` directory. +3. Any "binary" specified in the `composer.json` are linked and made accessible + in the derivation. + +As the autoloader optimization can be activated directly within the +`composer.json` file, we do not enable any autoloader optimization flags. + +To customize the PHP version, you can specify the `php` attribute. Similarly, if +you wish to modify the Composer version, use the `composer` attribute. It is +important to note that both attributes should be of the `derivation` type. + +Here's an example of working code example using `php.buildComposerProject`: + +```nix +{ php, fetchFromGitHub }: + +php.buildComposerProject (finalAttrs: { + pname = "php-app"; + version = "1.0.0"; + + src = fetchFromGitHub { + owner = "git-owner"; + repo = "git-repo"; + rev = finalAttrs.version; + hash = "sha256-VcQRSss2dssfkJ+iUb5qT+FJ10GHiFDzySigcmuVI+8="; + }; + + # PHP version containing the `ast` extension enabled + php = php.buildEnv { + extensions = ({ enabled, all }: enabled ++ (with all; [ + ast + ])); + }; + + # The composer vendor hash + vendorHash = "sha256-86s/F+/5cBAwBqZ2yaGRM5rTGLmou5//aLRK5SA0WiQ="; + + # If the composer.lock file is missing from the repository, add it: + # composerLock = ./path/to/composer.lock; +}) +``` + +In case the file `composer.lock` is missing from the repository, it is possible +to specify it using the `composerLock` attribute. + +The other method is to use all these methods and hooks individually. This has +the advantage of building a PHP library within another derivation very easily +when necessary. + +Here's a working code example to build a PHP library using `mkDerivation` and +separate functions and hooks: + +```nix +{ stdenvNoCC, fetchFromGitHub, php }: + +stdenvNoCC.mkDerivation (finalAttrs: +let + src = fetchFromGitHub { + owner = "git-owner"; + repo = "git-repo"; + rev = finalAttrs.version; + hash = "sha256-VcQRSss2dssfkJ+iUb5qT+FJ10GHiFDzySigcmuVI+8="; + }; +in { + inherit src; + pname = "php-app"; + version = "1.0.0"; + + buildInputs = [ php ]; + + nativeBuildInputs = [ + php.packages.composer + # This hook will use the attribute `composerRepository` + php.composerHooks.composerInstallHook + ]; + + composerRepository = php.mkComposerRepository { + inherit (finalAttrs) src; + # Specifying a custom composer.lock since it is not present in the sources. + composerLock = ./composer.lock; + # The composer vendor hash + vendorHash = "sha256-86s/F+/5cBAwBqZ2yaGRM5rTGLmou5//aLRK5SA0WiQ="; + }; +}) +``` diff --git a/doc/languages-frameworks/python.section.md b/doc/languages-frameworks/python.section.md index daf0740bcde05..ca0513fbde83d 100644 --- a/doc/languages-frameworks/python.section.md +++ b/doc/languages-frameworks/python.section.md @@ -724,8 +724,8 @@ We've now seen how to create an ad-hoc temporary shell session, and how to create a single script with Python dependencies, but in the course of normal development we're usually working in an entire package repository. -As explained in the Nix manual, `nix-shell` can also load an expression from a -`.nix` file. Say we want to have Python 3.11, `numpy` and `toolz`, like before, +As explained [in the `nix-shell` section](https://nixos.org/manual/nix/stable/command-ref/nix-shell) of the Nix manual, `nix-shell` can also load an expression from a `.nix` file. +Say we want to have Python 3.11, `numpy` and `toolz`, like before, in an environment. We can add a `shell.nix` file describing our dependencies: ```nix diff --git a/doc/languages-frameworks/ruby.section.md b/doc/languages-frameworks/ruby.section.md index f1953500fa329..3a4c94de92923 100644 --- a/doc/languages-frameworks/ruby.section.md +++ b/doc/languages-frameworks/ruby.section.md @@ -32,7 +32,8 @@ Again, it's possible to launch the interpreter from the shell. The Ruby interpre #### Load Ruby environment from `.nix` expression {#load-ruby-environment-from-.nix-expression} -As explained in the Nix manual, `nix-shell` can also load an expression from a `.nix` file. Say we want to have Ruby 2.6, `nokogori`, and `pry`. Consider a `shell.nix` file with: +As explained [in the `nix-shell` section](https://nixos.org/manual/nix/stable/command-ref/nix-shell) of the Nix manual, `nix-shell` can also load an expression from a `.nix` file. +Say we want to have Ruby 2.6, `nokogori`, and `pry`. Consider a `shell.nix` file with: ```nix with import <nixpkgs> {}; diff --git a/doc/preface.chapter.md b/doc/preface.chapter.md index 7aae7fa90591e..aa6acca1217a7 100644 --- a/doc/preface.chapter.md +++ b/doc/preface.chapter.md @@ -2,7 +2,7 @@ The Nix Packages collection (Nixpkgs) is a set of thousands of packages for the [Nix package manager](https://nixos.org/nix/), released under a -[permissive MIT/X11 license](https://github.com/NixOS/nixpkgs/blob/master/COPYING). +[permissive MIT license](https://github.com/NixOS/nixpkgs/blob/master/COPYING). Packages are available for several platforms, and can be used with the Nix package manager on most GNU/Linux distributions as well as [NixOS](https://nixos.org/nixos). diff --git a/doc/stdenv/meta.chapter.md b/doc/stdenv/meta.chapter.md index f6da0bb84be04..c187f0602a1e1 100644 --- a/doc/stdenv/meta.chapter.md +++ b/doc/stdenv/meta.chapter.md @@ -24,7 +24,8 @@ It is expected that each meta-attribute is one of the following: ### `description` {#var-meta-description} -A short (one-line) description of the package. This is shown by `nix-env -q --description` and also on the Nixpkgs release pages. +A short (one-line) description of the package. +This is displayed on [search.nixos.org](https://search.nixos.org/packages). Don’t include a period at the end. Don’t include newline characters. Capitalise the first character. For brevity, don’t repeat the name of package --- just describe what it does. @@ -74,7 +75,7 @@ The name of the main binary for the package. This affects the binary `nix run` e ### `priority` {#var-meta-priority} -The *priority* of the package, used by `nix-env` to resolve file name conflicts between packages. See the Nix manual page for `nix-env` for details. Example: `"10"` (a low-priority package). +The *priority* of the package, used by `nix-env` to resolve file name conflicts between packages. See the [manual page for `nix-env`](https://nixos.org/manual/nix/stable/command-ref/nix-env) for details. Example: `"10"` (a low-priority package). ### `platforms` {#var-meta-platforms} diff --git a/doc/stdenv/stdenv.chapter.md b/doc/stdenv/stdenv.chapter.md index fe0f5daf7a079..4e993e898de28 100644 --- a/doc/stdenv/stdenv.chapter.md +++ b/doc/stdenv/stdenv.chapter.md @@ -937,6 +937,28 @@ Like `stripDebugList`, but only applies to packages’ target platform. By defau Flags passed to the `strip` command applied to the files in the directories listed in `stripDebugList`. Defaults to `-S` (i.e. `--strip-debug`). +##### `stripExclude` {#var-stdenv-stripExclude} + +A list of filenames or path patterns to avoid stripping. A file is excluded if its name _or_ path (from the derivation root) matches. + +This example prevents all `*.rlib` files from being stripped: + +```nix +stdenv.mkDerivation { + # ... + stripExclude = [ "*.rlib" ] +} +``` + +This example prevents files within certain paths from being stripped: + +```nix +stdenv.mkDerivation { + # ... + stripExclude = [ "lib/modules/*/build/* ] +} +``` + ##### `dontPatchELF` {#var-stdenv-dontPatchELF} If set, the `patchelf` command is not used to remove unnecessary `RPATH` entries. Only applies to Linux. diff --git a/doc/using/overlays.chapter.md b/doc/using/overlays.chapter.md index a51aa9ee8fc54..6ee52215a4e18 100644 --- a/doc/using/overlays.chapter.md +++ b/doc/using/overlays.chapter.md @@ -24,7 +24,7 @@ The list of overlays is determined as follows. 2. Otherwise, if the Nix path entry `<nixpkgs-overlays>` exists, we look for overlays at that path, as described below. - See the section on `NIX_PATH` in the Nix manual for more details on how to set a value for `<nixpkgs-overlays>.` + See the [section on `NIX_PATH`](https://nixos.org/manual/nix/stable/command-ref/env-common.html#env-NIX_PATH) in the Nix manual for more details on how to set a value for `<nixpkgs-overlays>.` 3. If one of `~/.config/nixpkgs/overlays.nix` and `~/.config/nixpkgs/overlays/` exists, then we look for overlays at that path, as described below. It is an error if both exist. |