---
title: >-
    README
---

[pre alpha documentation (mostly a wish list)](docs/index.htm)

[copyright © and license](./license.txt)

pre-requisite, Pandoc to build the html documentation from the markdown files.

Windows pre-requisites:  Visual Studio and git-bash

To obtain the source code from which the project can be built,
including this README.html, from the bash command line (git-bash in windows).

```bash
git clone --recurse-submodules missing url
```

To build the docs, you need pandoc on the path.

```bash2
cd wallet/docs
./mkdocs.sh
```

To configure and build the required third party libraries in windows, then
build the program and run unit test for the first time, you need to have
Visual studio build tools at  their default location)

```bash2
cd wallet
./winConfigure.bat
```

Or, if you are in the command shell or power shell,

```bat
.\winConfigure.bat
```

After a pull from remote in which the submodules have changed, the pull
fails to automatically update the submodules by default, and when you
switch or checkout branches, the switch fails to automatically switch
and checkout the brances.

After a pull that gives you a status of modified submodules.

```bash
git submodule update --init --recursive --remote
```

After a checkout or branch switch that gives you a status of modified submodules.

```bash
git submodule update --recursive
```

The documentation is in pandoc flavored markdown, which is
 conveniently edited in vscode with the `markdown lint` and `Pandoc`
 extensions included and, if you have launched `code` in the docs directory,
 with  `file/preferences/Extensions/Markdown/Styles` set to
 `pandoc_templates\\style.css`, that being the style used by the `mkdocs.sh` documentation build script.

 On Windows, if Git Bash and Pandoc has been installed, you should be
 able to run this shell file in bash by double clicking on it.

if you add the recommended repository configuration defaults to your local repository configuration

```bash
git config --local include.path ../.gitconfig
```

this will substantially mitigate the problem of submodules failing to
update in pushes, pulls, checkouts, and switches.

[cryptographic software is under attack]:./docs/setup/contributor_code_of_conduct.html#code-will-be-cryptographically-signed
"Contributor Code of Conduct"
{target="_blank"}

It will, however, also implement signed commits, and insist you have set up a key pair as
explained in the contributor code of conduct because [cryptographic software is under attack] from NSA
entryists and shills, who seek to introduce backdoors.

`.gitconfig` also adds several git aliases:

1. `git lg` to display the git log with committer name from `.gitsigners` that corresponds to the public key
1. `git graph` to graph the commit tree with the committer name from `.gitsigners` that corresponds to the public key
1. `git alias` to display the git aliases.
1. `git utcmt` to make a commit without revealing your time zone.

[Pre alpha release](./RELEASE_NOTES.html), which means it does not yet work even well
enough for it to be apparent what it would do if it did work.