You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: README.rst
+122-2Lines changed: 122 additions & 2 deletions
Original file line number
Diff line number
Diff line change
@@ -416,7 +416,127 @@ Byron vote submission:
416
416
Development
417
417
****
418
418
419
-
Development tooling
419
+
Overview
420
+
====
421
+
422
+
The ``cardano-node`` development is primarily based on the Nix infrastructure (https://nixos.org/ ), which enables packaging, CI, development environments and deployments.
423
+
424
+
On how to set up Nix for ``cardano-node`` development, please see `Building Cardano Node with nix <https://github.com/input-output-hk/cardano-node/tree/master/doc/getting-started/building-the-node-using-nix.md>`_.
425
+
426
+
Workbench: a local cluster playground
427
+
====
428
+
429
+
You can quickly spin up a local cluster, based on any of a wide variety of configurations, and put it under a transaction generation workload -- using the ``workbench`` environment:
430
+
431
+
1. Optional: choose a workbench profile:
432
+
- ``default`` stands for a light-state, 6-node cluster, under saturation workload, indefinite runtime
433
+
- ``ci-test`` is the profile run in the node CI -- very light, just two nodes and short runtime
434
+
- ``devops`` is an unloaded profile (no transaction generation) with short slots -- ``0.2`` sec.
435
+
- ..and many more -- which can be either:
436
+
- listed, by ``make ps``
437
+
- observed at their point of definition: `nix/workbench/profiles/prof1-variants.jq <https://github.com/input-output-hk/cardano-node/tree/master/nix/workbench/profiles/prof1-variants.jq#L333-L526>`_
438
+
2. Optional: select mode of operation, by optionally providing a suffix:
439
+
- default -- no suffix -- just enter the workbench shell, allowing you to run ``start-cluster`` at any time. Binaries will be built locally, by ``cabal``.
440
+
- ``autostay`` suffix -- enter the workbench shell, start the cluster, and stay in the shell afterwards. Binaries will be built locally, by ``cabal``.
441
+
- ``autonix`` suffix -- enter the workbench shell, start the cluster. All binaries will be provided by the Nix CI.
442
+
- ..there are other modes, as per `lib.mk <https://github.com/input-output-hk/cardano-node/tree/master/lib.mk>`_
443
+
3. Enter the workbench shell for the chosen profile & mode:
444
+
``make <PROFILE-NAME>`` or ``make <PROFILE-NAME>-<SUFFIX>`` (when there is a suffix).
445
+
4. Optional: start cluster:
446
+
Depending on the chosen mode, your cluster might already start, or you are expected to start it yourself, using ``start-cluster``.
447
+
448
+
The workbench services are available only inside the workbench shell.
449
+
450
+
Using Cabal
451
+
----
452
+
453
+
By default, all binaries originating in the ``cardano-node`` repository are available to ``cabal build`` and ``cabal run``, unless the workbench was entered using one of the pure ``*nix`` modes. Note that in all cases, the dependencies for the workbench are supplied though Nix and have been built/tested on CI.
454
+
455
+
**Dependency localisation** -or- *Cabal&Nix for painless cross-repository work*
456
+
----
457
+
458
+
Normally, to work on ``cardano-node`` dependencies in the context of the node itself, one needs to go through an expensive multi-step process, mandated by the Nix model:
459
+
- Make changes to a dependency (say ``ouroboros-consensus-cardano`` in the ``ouroboros-network`` repository), commit them & push to Github.
460
+
- Calculate & bump the pin for that dependency in ``cardano-node``, inside its ``cabal.project``.
461
+
- Re-enter the Nix shell in ``cardano-node``, suffering full rebuilds of everything.
462
+
463
+
The **dependency localisation** workflow allows us to pick a subset of leaf dependencies of the ``cardano-node`` repository, and declare them *local* -- so they can be iterated upon using the ``cabal build`` / ``cabal run`` of ``cardano-node`` itself. This cuts development iteration time dramatically and enables effective cross-repo development of the full stack of Cardano packages.
464
+
465
+
Without further ado (**NOTE**: *the order of steps is important!*):
466
+
467
+
1. Ensure that your ``cardano-node`` checkout is clean, with no local modifications. Also, ensure that you start outside the node's Nix shell.
468
+
2. Check out the repository with the dependencies, *beside* the ``cardano-node`` checkout. You have to check out the git revision of the dependency used by your ``cardano-node`` checkout -- as listed in ``cardano-node/cabal.project``.
469
+
- we'll assume the ``ouroboros-network`` repository
470
+
- ..so a certain parent directory will include checkouts of both ``ouroboros-network`` and ``cardano-node``, at the same level
471
+
- ..and the git revision checked out in ``ouroboros-network`` will match the corresponding ``source-repository-package`` clause in ``cardano-node/cabal.project``.
472
+
- Extra point #1: you can localise/check out several dependency repositories
473
+
- Extra point #2: for the dependencies that are not listed in ``cabal.project`` of the node -- how do you determine the version to check out? You can ask the workbench shell:
474
+
1. Temporarily enter the workbench shell
475
+
2. Look for the package version in ``ghc-pkg list``
476
+
3. Use that version to determine the git revision of the dependency's repository (using a tag or some special knowledge about the version management of said dependency).
477
+
3. Enter the workbench shell, as per instructions in previous sections -- or just a plain Nix shell.
478
+
4. Ensure you can build ``cardano-node`` with Cabal: ``cabal build exe:cardano-node``. If you can't something else is wrong.
479
+
5. Determine the *leaf dependency set* you will have to work on. The *leaf dependency set* is defined to include the target package you want to modify, and its reverse dependencies -- that is, packages that depend on it (inside the dependency repository).
480
+
- let's assume, for example, that you want to modify ``ouroboros-consensus-shelley``
481
+
- ``ouroboros-consensus-shelley`` is not a leaf dependency in itself, since ``ouroboros-consensus-cardano`` (of the same ``ouroboros-network`` repository) depends on it -- so the *leaf dependency set* will include both of them.
482
+
- you might find out that you have to include a significant fraction of packages in ``ouroboros-network`` into this *leaf dependency set* -- do not despair.
483
+
6. Edit the ``cardano-node/cabal.project`` as follows:
484
+
- for the *leaf dependency set*
485
+
1. in the very beginning of the ``cabal.project``, add their relative paths to the ``packages:`` section, e.g.:
486
+
.. code-block:: console
487
+
488
+
packages:
489
+
cardano-api
490
+
cardano-cli
491
+
...
492
+
trace-resources
493
+
trace-forward
494
+
../ouroboros-network/ouroboros-consensus-shelley
495
+
../ouroboros-network/ouroboros-consensus-cardano
496
+
497
+
2. in the corresponding ``source-repository-package`` section, comment out mentions of the packages, e.g.:
7. The two packages have now became **local** -- when you try ``cabal build exe:cardano-node`` now, you'll see that Cabal starts to build these dependencies you just localised. Hacking time!
518
+
519
+
Hoogle
520
+
----
521
+
522
+
The workbench shell provides ``hoogle``, with a local database for the full set of dependencies:
0 commit comments