Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

update dev instructions #147

Open
wants to merge 1 commit into
base: master
Choose a base branch
from
Open

update dev instructions #147

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
151 changes: 116 additions & 35 deletions docs/howto/cylc-ui.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,5 +1,9 @@
# Getting Started with Cylc 8

Say hi on the
[Cylc developers chat](https://matrix.to/#/#cylc-general:matrix.org).


## Development Installation

> **Note**: We recommend developing in a Conda environment as this provides a
Expand All @@ -17,65 +21,105 @@
(and `configurable-http-proxy` if working with JupyterHub):

```bash
conda create -n cylc-8-dev python=3.7 configurable-http-proxy -f conda-environment.yml
conda create -n cylc-<version> python=3.7 configurable-http-proxy -f conda-environment.yml
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

If we want to use -f we need to use conda env create?

Suggested change
conda create -n cylc-<version> python=3.7 configurable-http-proxy -f conda-environment.yml
conda env create -n cylc-<version> -f conda-environment.yml

However, this will error with the chaining of the configurable-http-proxy. Add the configurable http proxy later, after activation?

Python version here is 3.7, however after executing this, the python version is 3.9.10. Maybe better removing the 3.7 as it is being upgraded anyway?

Also, maybe worth pointing out they should be in the cylc-flow dir, or change the -f path?

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yep, chaining deps doesn't work here.

Would need to edit the file to add deps, which is icky.

My personal solution is a script which copies the env file, adds a few deps, lists the local Python repos I want to install, then installs from that.

```

2. Install Python Projects
Where `<version>` is the cylc-flow version e.g. `8.0.1`.

2. Fork & Clone the repos you want to develop:

* [cylc/cylc-flow](https://github.com/cylc/cylc-flow/)

[optional] For Isodatetime development:

* [metomi/metomi-isodatetime](https://github.com/metomi/metomi-isodatetime/)

[optional] For ui development:

Install [cylc/cylc-flow](https://github.com/cylc/cylc-flow/) and optionally:
* [cylc/cylc-ui](https://github.com/cylc/cylc-uiserver/)
* [cylc/cylc-uiserver](https://github.com/cylc/cylc-uiserver/)

* [cylc/cylc-uiserver](https://github.com/cylc/cylc-uiserver/) (for UIS work)
* [metomi/metomi-rose](https://github.com/metomi/metomi-rose/) (for Rose work)
* [cylc/cylc-rose](https://github.com/cylc/cylc-rose/) (for Rose work)
[optional] For Rose development:

* [metomi/metomi-rose](https://github.com/metomi/metomi-rose/)
* [cylc/cylc-rose](https://github.com/cylc/cylc-rose/)

3. Install Python Projects

Pip-install any Python projects you want to work with in editable mode
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Worth adding a check that master is checked out and up to date?

in the following order:

```bash
# clone the git repository locally then...
pip install -e "path/to/repo[all]"
pip install -e "metomi-isodatetime[all]"
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Installing this, followed by cylc flow results in my editable isodatetime being overridden (confirmed with pip list before and after each install), should this order swap?

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Confusingly no, the issue is that cylc-flow does not support isodatetime@master ATM.

pip install -e "cylc-flow[all]"
pip install -e "cylc-uiserver[all]"
pip install -e "metomi-rose[all]"
pip install -e "cylc-rose[all]"
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Do we want to add cylc-sphinx extensions and cylc-doc or keep it to the core repos?

```

3. Install [cylc/cylc-ui](https://github.com/cylc/cylc-ui/).
> **Note:** If you install the projects in the wrong order you might
> end up installing released versions from PyPi, use `pip list` to check.

> **Note:** We prefer `yarn`.
4. [optional] Configure Cylc Flow for distributed development

> Required to work with cylc-flow on multiple hosts in a network.

You need to ensure that Cylc is installed and accessible on all of the hosts
you want to work with.

You will need to synchronise your environments to any hosts that have an
independent `$HOME` filesystem.

If you are working on a site which installs Cylc for you ensure the Cylc
[wrapper script
](https://github.com/cylc/cylc-flow/blob/master/cylc/flow/etc/cylc)
is in your "$PATH". Otherwise install it yourself (read comments in file).

Export the `CYLC_HOME_ROOT_ALT` varaible to point at your Conda "envs"
directory in your `~/.bash_profile` file e.g:

```bash
cd path/to/cylc-ui
yarn install
# add the wrapper script to $PATH
export PATH="/path/to/wrapper/script:$PATH"
# set the path to your development environments
export CYLC_HOME_ROOT_ALT=/home/me/mambaforge/envs/
```

4. Point Cylc Hub at your UI build
The same wrapper script can be used for Rose & Isodatetime

The Cylc UI comes bundled with the UI Server.
5. [optional] Install [cylc/cylc-ui](https://github.com/cylc/cylc-ui/).

If you want to develop the UI you will need to point the UI Server at
your local UI build:
> Required for cylc-ui development

```python
# ~/.cylc/hub/jupyter_config.py
c.CylcUIServer.ui_build_dir = '~/cylc-ui/dist' # path to build
```
> **Note:** We prefer `yarn`.

(see the cylc-uiserver README for more information)
> **Note:** The UI must currently be built with Node<=16 (2022-03-03)

5. Build The UI
Install Node dependencies:

```bash
yarn run build:watch
cd path/to/cylc-ui
yarn install
```

(see the cylc-ui README for more information)

6. Launch the UI
Build the UI with either:

```bash
# standalone
cylc gui
yarn run build
yarn run build:watch
```

# via Jupyter Hub
cylc hub
# You will be asked to log in with your desktop credentials if you have not
# done so before.
To use your development build point the UIS at the build directory:

```python
# ~/.cylc/uiserver/jupyter_config.py
# use a development UI build rather than the build bundled with the UIS
c.CylcUIServer.ui_build_dir = '~/cylc-ui/dist' # path to build
```

The version number should appear in the bottom-right of the UI along with the
word development.

(see the cylc-uiserver README for more information)


Expand All @@ -100,22 +144,59 @@
__HERE__
```

2. Run the workflow:
2. Activate your environment:

```bash
conda activate cylc-<version>
```

3. Run the workflow:

```bash
cylc play foo
```

3. Watch it run on the CLI:
4. Watch it run on the CLI:

```bash
cylc tui foo
```

4. Stop it:
5. Watch it run from the GUI:

```bash
cylc gui
```

6. Stop it:

(otherwise it will just keep running forever)

```bash
cylc stop foo
```


## Working On Python Projects

You will need your Conda environment activated in order to run the tests.

```bash
conda activate cylc-<version>
```

The Cylc wrapper script will automatically activate your environment on other
hosts around the network.

The `CYLC_VERSION` and `CYLC_ENV_NAME` environment variables make this happen:

```
CYLC_VERSION=8.0.0 cylc version --long
8.0.0 ...
```

We use `flake8` for linting and `pytest` for testing, check the README files in
each repo you work with.

You will need to re-pip install after any changes to packaging
(i.e. setup.cfg files), good idea to do this out of habit.