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

Tidying up the README #196

Merged
merged 6 commits into from
Apr 4, 2019
Merged

Tidying up the README #196

Show file tree
Hide file tree
Changes from 5 commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
1fa73c1
Tidying up the README
bethaitman-da Apr 4, 2019
dd57bfa
Tidying contributing page as well
bethaitman-da Apr 4, 2019
d18b7ac
Apply review suggestion
gerolf-da Apr 4, 2019
0d26a41
Address more review comments
bethaitman-da Apr 4, 2019
57e81a7
Address review comment
bethaitman-da Apr 4, 2019
940e5b2
Merge branch 'master' into readme-tidy
bethaitman-da Apr 4, 2019
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
8 changes: 5 additions & 3 deletions CONTRIBUTING.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,10 +1,12 @@
# Contributing to DAML

Welcome! This document provides a high-level overview of how to contribute to the development of DAML.
Welcome! This page gives a high-level overview of how to contribute to the development of DAML.

(For information on how to build, test, and work on the codebase, see the [README](./README.md).)
There are many ways you can contribute beyond coding. For example, you can report problems, clarify [issues](https://github.com/digital-asset/daml/issues), and write documentation. If you're completely new to open source development, the [Open Source Guides](https://opensource.guide) is a great place to start.

There are many ways you can contribute beyond coding. For example, you can report problems, report and clarify issues, and write documentation. If you're completely new to open source, the [Open Source Guides](https://opensource.guide) is a great place to start.
## Working on the codebase

For information on how to build, test, and work on the codebase, see ["To start contributing to DAML" in the README](./README.md#to-start-contributing-to-daml).

## Code of conduct

Expand Down
69 changes: 42 additions & 27 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,57 +5,70 @@ SPDX-License-Identifier: Apache-2.0

# Welcome to the DAML repository!

This repository hosts all code for the DAML smart contract language, originally created by [Digital Asset](https://www.digitalasset.com).
This repository hosts all code for the DAML smart contract language, originally created by
[Digital Asset](https://www.digitalasset.com).

## To start using DAML

See our documentation at [docs.daml.com](https://docs.daml.com).
To download DAML, follow [the installation instructions on docs.daml.com](https://docs.daml.com/getting-started/installation.html).
To try out using it, follow the [quickstart guide](https://docs.daml.com/getting-started/quickstart.html).

Download the DAML SDK Developer Preview at [https://www.daml.com](https://www.daml.com).

If you have questions about how to use DAML or how to build DAML-based solutions, please ask them on [StackOverflow using the `daml` tag](https://stackoverflow.com/tags/daml).
If you have questions about how to use DAML or how to build DAML-based solutions, please ask
them on [StackOverflow using the `daml` tag](https://stackoverflow.com/tags/daml).

## To start contributing to DAML

We warmly welcome [contributions](./CONTRIBUTING.md).

### Cloning this repository
### 1. Clone this repository
`git clone git@github.com:DACH-NY/daml.git`.

### Setting up the DA Development Environment (also known as `dev-env`)
dev-env is used to provide dependencies required during build phase, like java,
bazel, and python for some tooling scripts, while the code itself is built through
bazel.
### 2. Set up the DA Development Environment ("`dev-env`")

`dev-env` provides dependencies required during the build phase, like Java, Bazel, and Python
for some tooling scripts. The code itself is built using Bazel.

#### Set up `dev-env` on Linux or macOS

#### Linux and macOS
1. Install Nix: `bash <(curl https://nixos.org/nix/install)`
2. Enter dev-env: `eval "$(dev-env/bin/dade assist)"`
2. Enter `dev-env`: `eval "$(dev-env/bin/dade assist)"`

If you don't want to enter `dev-env` manually each time using `eval "$(dev-env/bin/dade assist)"`,
you can also install [direnv](https://direnv.net). This repo already provides a `.envrc`
file, with an option to add more in a `.envrc.private` file.

#### Set up `dev-env` on Windows

We're working on Windows support (for both end users and developers), but it's not ready yet.
[Sign up](https://hub.daml.com/sdk/windows) to be notified when it is available.

To avoid entering dev-env manually each time through `eval "$(dev-env/bin/dade
assist)"`, you can also install [direnv](https://direnv.net).
### 3. Build the source code

This repo already provides a `.envrc` file, with an option to add more in a
`.envrc.private` file.
Run `bazel build //...`

#### Windows
We're working on Windows support (both users and developers), but it's not ready yet. [Sign up](https://hub.daml.com/sdk/windows) to be notified when it is available.
This builds the code and runs the tests, and will likely take an hour or more.

### Build the source code
`bazel build //...`. This will likely take an hour or more.
Now you've built, rebuilding the code after a change will be much faster because Bazel caches
unchanged build artefacts. To read more about Bazel and how to use it, see [the Bazel site](https://bazel.build).

You have now built the code and run the tests. Rebuilding the code after a change will be significantly faster because Bazel caches unchanged build artefacts. You can read more about Bazel and how to use it [here](https://bazel.build).
To just run the tests, run `bazel test //...`

4. Run the tests: `bazel test //...`
### 4. Contribute!

If you are looking for ideas on how to contribute, please browse our [issues](https://github.com/DACH-NY/daml/issues).
If you are looking for ideas on how to contribute, please browse our
[issues](https://github.com/DACH-NY/daml/issues).

### Caching: build speed and disk space considerations

Bazel has a lot of nice properties, but they come at the cost of frequently rebuilding "the world". To make that bearable, we make extensive use of caching. Most artifacts should be cached in our CDN, which is configured in `.bazelrc` in this project.
Bazel has a lot of nice properties, but they come at the cost of frequently rebuilding "the world".
To make that bearable, we make extensive use of caching. Most artifacts should be cached in our CDN,
which is configured in `.bazelrc` in this project.

However, even then, you may end up spending a lot of time (and bandwidth!) downloading artifacts from the CDN. To alleviate that, by default, our build will create a subfolder `.bazel-cache` in this project and keep an on-disk cache. **This can take about 10GB** at the time of writing.
However, even then, you may end up spending a lot of time (and bandwidth!) downloading artifacts from
the CDN. To alleviate that, by default, our build will create a subfolder `.bazel-cache` in this
project and keep an on-disk cache. **This can take about 10GB** at the time of writing.

To disable the disk cache, simply remove the following lines:
To disable the disk cache, remove the following lines:

```
build:linux --disk_cache=.bazel-cache
Expand All @@ -64,4 +77,6 @@ build:darwin --disk_cache=.bazel-cache

from the `.bazelrc` file.

If you work with multiple copies of this repository, you can point all of them to the same disk cache by overwriting these configs in either a `.bazelrc.local` file in each copy, or a `~/.bazelrc` file in your home directory.
If you work with multiple copies of this repository, you can point all of them to the same disk cache
by overwriting these configs in either a `.bazelrc.local` file in each copy, or a `~/.bazelrc` file
in your home directory.