1

# Beremiz public distribution #

     2

     3

This repository holds recipes and patches to build the Beremiz 

     4

packages and installers for [Beremiz website](http://beremiz.org/).

     5

     6

Patches have same license as projects being patched. For other files,

     7

unless made explicit in file header, GPLv3 applies.

     8

     9

## Use cases ##

    10

    11

Beremiz development uses Mercurial, but git repositories that are kept in sync.

    12

    13

Build from both Mercurial and Git repositories is supported.

    14

    15

### GitHub CI ##

    16

    17

Use code from https://github.com/beremiz repositories.

    18

    19

Workflows described in .github/workflows are meant to run on a GitHub runner. Please refer to GitHub documentation to run workflows on your own fork.

    20

    21

Dockerfile and part of Makefiles are used for windows installer build, but for Snap build, only snapcraft.yaml is used.

    22

    23

### Manual build ###

    24

    25

Use code from your local Mercurial repositories, cloned from https://hg.beremiz.org

    26

    27

Uses Makefiles and Dockerfile to build windows installer and Makefile+snapcraft.yaml for Snap package.

    28

    29

Hereafter is documented how to use Makefile and Docker in case of Manual Build

    30

    31

## Prerequisites ##

    32

    33

A usable Docker is required. Docker is used to ensure a reproducible build

    34

environment. 

    35

    36

Other containerization/virtualization could be used to achieve the same effect. 

    37

    38

Reference build environment is obtained by applying [provision_focal64.sh](provision_focal64.sh) on Ubuntu 20.04 amd64.

    39

    40

## Preparing source ##

    41

    42

The top Makefile expects source code of Beremiz, Matiec and CanFestival to be 

    43

sibling to beremiz_public_dist directory, in the 'source directory'.

    44

For example :

    45

    46

```

    47

~/src

    48

     /beremiz

    49

     /beremiz_public_dist

    50

     /canfestival

    51

     /matiec

    52

     /Modbus

    53

```

    54

    55

Repositories can be cloned from https://hg.beremiz.org .

    56

    57

Intermediate and final results are all placed in a single 'build directory'

    58

during build process.

    59

    60

## Windows installer Build ##

    61

    62

### Prepare Docker image ###

    63

    64

The script [rebuild_docker.sh](rebuild_docker.sh) is used for that purpose.

    65

    66

Synopsis:

    67

    68

    ./rebuild_docker.sh [build directory]

    69

    70

Example:

    71

    72

```

    73

#!sh

    74

mkdir ~/src ~/build

    75

cd ~/src

    76

hg clone https://hg.beremiz.org/beremiz_public_dist

    77

cd beremiz_public_dist

    78

./rebuild_docker.sh

    79

```

    80

    81

Source and Build Volumes :

    82

    83

 Role             | Docker Volume     | Host path in example | Rationale

    84

------------------|-------------------|----------------------|------------------------------------------------

    85

 source directory | /home/devel/src   | ~/src                | Always relative to CWD : "../"

    86

 build directory  | /home/devel/build | ~/build              | First argument to rebuild_docker.sh or ~/build

    87

    88

'build directory' can be specified as absolute path argument of rebuild_docker.sh.

    89

If not specified it defaults to ~/build

    90

    91

```

    92

#!sh

    93

./rebuild_docker.sh ~/build_next

    94

```

    95

    96

Note: 'build directory' is created if not already existing.

    97

    98

### Build Windows Installer ###

    99

   100

The script [build_in_docker.sh](build_in_docker.sh) is used for that purpose.

   101

   102

```

   103

#!sh

   104

./build_in_docker.sh 

   105

```

   106

   107

Note: 'build directory' must exist before calling build_in_docker.sh, otherwise

   108

Docker will create it as root user. Be sure to create it again if you delete it.

   109

   110

Resulting installer is Beremiz-${timestamp}.exe in 'build directory'. 

   111

   112

### Manhole ###

   113

   114

Once Docker image ready, the scripts [enter_docker.sh](enter_docker.sh) and

   115

[enter_docker_as_root.sh](enter_docker_as_root.sh) let you issue build 

   116

commands, or install additional packages.

   117

   118

[clean_docker_container.sh](clean_docker_container.sh) and [create_docker_container.sh](create_docker_container.sh) and 

   119

[clean_docker_image.sh](clean_docker_image.sh) and [build_docker_image.sh](build_docker_image.sh) are invoked by 

   120

[rebuild_docker.sh](rebuild_docker.sh). 

   121

   122

## Snap Package Build ##

   123

   124

snapcraft.yaml does not rely on HG or GIT repos, but refers to local sources, this is responsibility of caller to prepare sources for snapcraft.

   125

   126

Reasons for this are :

   127

 - no parameters or conditional variables exist to tell snapcraft.yaml where to get the source from

   128

 - building from local source should be always possible

   129

 - revisions.txt must be updated in any case so that it is always possible to know what version wqas used to build resulting package

   130

 - when Snap is built from GitHub actions, Makefile isn't used at all, and GitHub action workflow organize sources and revisions.txt on its own.

   131

   132

In the end, instead of just calling `snapcraft` to get a snap package, it is more complicated:

   133

   134

```

   135

#!sh

   136

mkdir ~/src ~/build

   137

cd ~/src

   138

hg clone https://hg.beremiz.org/beremiz_public_dist

   139

cd ~/build

   140

make -f ~/src/beremiz_public_dist/Makefile DIST=snap

   141

   142

```

   143

Resulting snap package is sources/beremiz_${version}_${platform}.snap.

   144

It can be installed this way:

   145

   146

```

   147

sudo snap install sources/beremiz_1.3-beta2_amd64.snap --dangerous --devmode

   148

```

   149