<commit_before># Hacking on Cockpit

Here's where to get the code:

    $ git clone https://github.com/cockpit-project/cockpit
    $ cd cockpit/

The remainder of the commands assume you're in the top level of the
Cockpit git repository checkout.

## Getting the development dependencies

Cockpit uses Node.js during development. Node.js is not used at runtime.
To make changes on Cockpit you'll want to install Node.js, NPM and
various development dependencies like Webpack.

On Debian and Ubuntu, the available versions of nodejs and npm are old
and/or incompatible with each other.  You should not try to use them to
build cockpit.  You can use the helpful "n" utility to get a more
reasonable environment to work with.

    $ sudo apt-get install nodejs npm
    $ sudo npm install -g n
    $ sudo apt-get remove nodejs npm
    $ sudo n lts

On Fedora, the distribution versions are sufficient:

    $ sudo dnf install nodejs npm

And lastly get Webpack and the development dependencies:

    $ sudo npm install -g webpack
    $ npm install

When relying on CI to run the test suite, this is all that is
necessary to work on the JavaScript components of Cockpit.

To actually build the Cockpit binaries themselves from source
(including to run the integration tests locally), you will need
additional header files and other components. Check
`tools/cockpit.spec` for the concrete Fedora build dependencies.

Note that `tools/cockpit.spec` is a template filled in by
`tools/gen-spec-dependencies`, and cannot be directly parsed by dnf.
The following should work in a fresh Git clone:

    $ sudo dnf install dnf-utils
    $ TEMPFILE=$(mktemp -u --suffix=.spec) && \
      sed 's/%{npm-version:.*}/0/' tools/cockpit.spec >$TEMPFILE && \
      sudo dnf builddep --spec $TEMPFILE && \
      rm $TEMPFILE

For running integration tests, the following dependencies are required:

    $ sudo dnf install curl expect xz rpm-build chromium-headless \
        libvirt-daemon-kvm libvirt-client python3-libvirt

Creating VM images locally (not necessary for running tests) needs the following:

    $ sudo dnf install virt-install

## Building

Cockpit uses the autotools and thus there are the familiar `./configure`
script and Makefile targets.

After a fresh clone of the Cockpit sources, you need to prepare them by running
`autogen.sh` like this:

    $ ./autogen.sh --prefix=/usr --enable-debug

As shown, `autogen.sh` runs 'configure' with the given options, and it
also prepares the build tree by downloading various nodejs dependencies.

When working with a Git clone, it is therefore best to simply always
run `./autogen.sh` instead of `./configure`.

Then run

    $ make

to build everything.  Cockpit has a single non-recursive Makefile.  You can
only run `make` from the top-level and it will always rebuild the whole
project.

You can run unit tests of the current checkout:

    $ make check

These should finish very quickly and it is good practice to do it
often.

For debugging individual tests, there are compiled binaries in the
build directory. For QUnit tests (JavaScript), you can run

    $ ./test-server

which will output a URL to connect to with a browser, such as
`http://localhost:8765/dist/base1/test-dbus.html`. Adjust the path
for different tests and inspect the results there.

You can also run individual tests by specifying the `TESTS` environment
variable:

    $ make check TESTS=dist/base1/test-chan.html

There are also static code and syntax checks which you should run often:

    $ tools/test-static-code

It is highly recommended to set this up as a git pre-push hook, to avoid
pushing PRs that will fail on trivial errors:

    $ ln -s ../../tools/test-static-code .git/hooks/pre-push

## Running the integration test suite

Refer to the [testing README](test/README.md) for details on running
the Cockpit integration tests locally.

## Running eslint

Cockpit uses [ESLint](https://eslint.org/) to automatically check
JavaScript code style in `.js` and `.jsx` files.

The linter is executed within every build as a webpack preloader.

For developer convenience, the ESLint can be started explicitly by:

    $ npm run eslint

Violations of some rules can be fixed automatically by:

    $ npm run eslint:fix

Rules configuration can be found in the `.eslintrc.json` file.

## Working on your local machine: Cockpit's session pages

It's easy to set up your local Linux machine for rapid development of Cockpit's
JavaScript code (in pkg/). First install Cockpit on your local machine as described in:

https://cockpit-project.org/running.html

Next run this command from your top level Cockpit checkout directory, and make
sure to run it as the same user that you'll use to log into Cockpit below.

    $ mkdir -p ~/.local/share/
    $ ln -s $(pwd)/dist ~/.local/share/cockpit

This will cause cockpit to read JavaScript and HTML files directly from the built
package output directory instead of using the installed Cockpit UI files.

Now you can log into Cockpit on your local Linux machine at the following address.
Use the same user and password that you used to log into your Linux desktop.

http://localhost:9090

After every change to your sources, run `make` to update all the webpacks, and
reload cockpit in your browser.

To make Cockpit again use the installed code, rather than that from your
git checkout directory, run the following, and log into Cockpit again:

    $ rm ~/.local/share/cockpit

## Working on your local machine: Web server resources

To test changes to the login page or any other resources, you can bind-mount
the build tree's `dist/static/` directory over the  system one:

    $ sudo mount -o bind dist/static/ /usr/share/cockpit/static/

Likewise, to test changes to the branding, use

    $ sudo mount -o bind src/branding/ /usr/share/cockpit/branding/

After that, run `systemctl stop cockpit.service` to ensure that the web server
restarts on the next browser request.

To make Cockpit again use the system-installed code, simply umount these again:

    $ sudo umount /usr/share/cockpit/static/ /usr/share/cockpit/branding/
    $ systemctl stop cockpit.service

## Working on Cockpit using Vagrant

It is also possible to use a Vagrant virtual machine to develop Cockpit.

Most of Cockpit is written in JavaScript. Almost all of this code is found
in the packages in the pkg/ subdirectory of the Cockpit git checkout.

To use Vagrant to develop Cockpit, run in its top level git checkout.<commit_msg>HACKING: Document how to use locally built cockpit-ws<commit_after># Hacking on Cockpit

Here's where to get the code:

    $ git clone https://github.com/cockpit-project/cockpit
    $ cd cockpit/

The remainder of the commands assume you're in the top level of the
Cockpit git repository checkout.

## Getting the development dependencies

Cockpit uses Node.js during development. Node.js is not used at runtime.
To make changes on Cockpit you'll want to install Node.js, NPM and
various development dependencies like Webpack.

On Debian and Ubuntu, the available versions of nodejs and npm are old
and/or incompatible with each other.  You should not try to use them to
build cockpit.  You can use the helpful "n" utility to get a more
reasonable environment to work with.

    $ sudo apt-get install nodejs npm
    $ sudo npm install -g n
    $ sudo apt-get remove nodejs npm
    $ sudo n lts

On Fedora, the distribution versions are sufficient:

    $ sudo dnf install nodejs npm

And lastly get Webpack and the development dependencies:

    $ sudo npm install -g webpack
    $ npm install

When relying on CI to run the test suite, this is all that is
necessary to work on the JavaScript components of Cockpit.

To actually build the Cockpit binaries themselves from source
(including to run the integration tests locally), you will need
additional header files and other components. Check
`tools/cockpit.spec` for the concrete Fedora build dependencies.

Note that `tools/cockpit.spec` is a template filled in by
`tools/gen-spec-dependencies`, and cannot be directly parsed by dnf.
The following should work in a fresh Git clone:

    $ sudo dnf install dnf-utils
    $ TEMPFILE=$(mktemp -u --suffix=.spec) && \
      sed 's/%{npm-version:.*}/0/' tools/cockpit.spec >$TEMPFILE && \
      sudo dnf builddep --spec $TEMPFILE && \
      rm $TEMPFILE

For running integration tests, the following dependencies are required:

    $ sudo dnf install curl expect xz rpm-build chromium-headless \
        libvirt-daemon-kvm libvirt-client python3-libvirt

Creating VM images locally (not necessary for running tests) needs the following:

    $ sudo dnf install virt-install

## Building

Cockpit uses the autotools and thus there are the familiar `./configure`
script and Makefile targets.

After a fresh clone of the Cockpit sources, you need to prepare them by running
`autogen.sh` like this:

    $ ./autogen.sh --prefix=/usr --enable-debug

As shown, `autogen.sh` runs 'configure' with the given options, and it
also prepares the build tree by downloading various nodejs dependencies.

When working with a Git clone, it is therefore best to simply always
run `./autogen.sh` instead of `./configure`.

Then run

    $ make

to build everything.  Cockpit has a single non-recursive Makefile.  You can
only run `make` from the top-level and it will always rebuild the whole
project.

You can run unit tests of the current checkout:

    $ make check

These should finish very quickly and it is good practice to do it
often.

For debugging individual tests, there are compiled binaries in the
build directory. For QUnit tests (JavaScript), you can run

    $ ./test-server

which will output a URL to connect to with a browser, such as
`http://localhost:8765/dist/base1/test-dbus.html`. Adjust the path
for different tests and inspect the results there.

You can also run individual tests by specifying the `TESTS` environment
variable:

    $ make check TESTS=dist/base1/test-chan.html

There are also static code and syntax checks which you should run often:

    $ tools/test-static-code

It is highly recommended to set this up as a git pre-push hook, to avoid
pushing PRs that will fail on trivial errors:

    $ ln -s ../../tools/test-static-code .git/hooks/pre-push

## Running the integration test suite

Refer to the [testing README](test/README.md) for details on running
the Cockpit integration tests locally.

## Running eslint

Cockpit uses [ESLint](https://eslint.org/) to automatically check
JavaScript code style in `.js` and `.jsx` files.

The linter is executed within every build as a webpack preloader.

For developer convenience, the ESLint can be started explicitly by:

    $ npm run eslint

Violations of some rules can be fixed automatically by:

    $ npm run eslint:fix

Rules configuration can be found in the `.eslintrc.json` file.

## Working on your local machine: Cockpit's session pages

It's easy to set up your local Linux machine for rapid development of Cockpit's
JavaScript code (in pkg/). First install Cockpit on your local machine as described in:

https://cockpit-project.org/running.html

Next run this command from your top level Cockpit checkout directory, and make
sure to run it as the same user that you'll use to log into Cockpit below.

    $ mkdir -p ~/.local/share/
    $ ln -s $(pwd)/dist ~/.local/share/cockpit

This will cause cockpit to read JavaScript and HTML files directly from the built
package output directory instead of using the installed Cockpit UI files.

Now you can log into Cockpit on your local Linux machine at the following address.
Use the same user and password that you used to log into your Linux desktop.

http://localhost:9090

After every change to your sources, run `make` to update all the webpacks, and
reload cockpit in your browser.

To make Cockpit again use the installed code, rather than that from your
git checkout directory, run the following, and log into Cockpit again:

    $ rm ~/.local/share/cockpit

## Working on your local machine: Web server

To test changes to the login page or any other resources, you can bind-mount
the build tree's `dist/static/` directory over the  system one:

    $ sudo mount -o bind dist/static/ /usr/share/cockpit/static/

Likewise, to test changes to the branding, use

    $ sudo mount -o bind src/branding/ /usr/share/cockpit/branding/

After that, run `systemctl stop cockpit.service` to ensure that the web server
restarts on the next browser request.

To make Cockpit again use the system-installed code, simply umount these again:

    $ sudo umount /usr/share/cockpit/static/ /usr/share/cockpit/branding/
    $ systemctl stop cockpit.service

Similarly, if you change cockpit-ws itself, you can make the system (systemd
units, cockpit-tls, etc.) use that:

    $ sudo mount -o bind cockpit-ws /usr/libexec/cockpit-ws

On Debian based OSes, the path will be `/usr/lib/cockpit/cockpit-ws` instead.
You need to disable SELinux with

    $ sudo setenforce 0

for this to work, as your local build tree does not otherwise have the expected
SELinux type.

## Working on Cockpit using Vagrant

It is also possible to use a Vagrant virtual machine to develop Cockpit.

Most of Cockpit is written in JavaScript. Almost all of this code is found
in the packages in the pkg/ subdirectory of the Cockpit git checkout.

To use Vagrant to develop Cockpit, run in its top level git checkout.
{'fraction_non_alphanumeric': 0.06146836955709911, 'fraction_numerical': 0.0018672044215400701, 'mean_word_length': 3.678546470999301, 'pattern_counts': {'":': 0, '<': 3, '<?xml version=': 0, '>': 5, 'https://': 6, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 2, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '1001926', 'n_tokens_mistral': 3831, 'n_tokens_neox': 3567, 'n_words': 1902}