edouard@37: # Beremiz public distribution #
edouard@37: 
edouard@103: This repository holds recipes and patches to build the Beremiz 
edouard@103: packages and installers for [Beremiz website](http://beremiz.org/).
edouard@37: 
edouard@103: Patches have same license as projects being patched. For other files,
edouard@37: unless made explicit in file header, GPLv3 applies.
edouard@37: 
edouard@103: ## Use cases ##
edouard@103: 
edouard@103: Beremiz development uses Mercurial, but git repositories that are kept in sync.
edouard@103: 
edouard@103: Build from both Mercurial and Git repositories is supported.
edouard@103: 
edouard@103: ### GitHub CI ##
edouard@103: 
edouard@103: Use code from https://github.com/beremiz repositories.
edouard@103: 
edouard@103: 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.
edouard@103: 
edouard@103: Dockerfile and part of Makefiles are used for windows installer build, but for Snap build, only snapcraft.yaml is used.
edouard@103: 
edouard@103: ### Manual build ###
edouard@103: 
edouard@103: Use code from your local Mercurial repositories, cloned from https://hg.beremiz.org
edouard@103: 
edouard@103: Uses Makefiles and Dockerfile to build windows installer and Makefile+snapcraft.yaml for Snap package.
edouard@103: 
edouard@103: Hereafter is documented how to use Makefile and Docker in case of Manual Build
edouard@37: 
edouard@37: ## Prerequisites ##
edouard@37: 
edouard@37: A usable Docker is required. Docker is used to ensure a reproducible build
edouard@37: environment. 
edouard@37: 
edouard@37: Other containerization/virtualization could be used to achieve the same effect. 
edouard@37: 
edouard@37: Reference build environment is obtained by applying [provision_focal64.sh](provision_focal64.sh) on Ubuntu 20.04 amd64.
edouard@37: 
edouard@80: ## Preparing source ##
edouard@37: 
edouard@37: The top Makefile expects source code of Beremiz, Matiec and CanFestival to be 
edouard@37: sibling to beremiz_public_dist directory, in the 'source directory'.
edouard@37: For example :
edouard@37: 
edouard@37: ```
edouard@37: ~/src
edouard@37:      /beremiz
edouard@37:      /beremiz_public_dist
edouard@37:      /matiec
edouard@123:      /canfestival [optional]
edouard@123:      /Modbus      [optional]
edouard@123:      /open62541   [optional]
edouard@37: ```
edouard@37: 
edouard@103: Repositories can be cloned from https://hg.beremiz.org .
edouard@37: 
edouard@37: Intermediate and final results are all placed in a single 'build directory'
edouard@37: during build process.
edouard@37: 
edouard@80: ## Windows installer Build ##
edouard@80: 
edouard@37: ### Prepare Docker image ###
edouard@37: 
edouard@37: The script [rebuild_docker.sh](rebuild_docker.sh) is used for that purpose.
edouard@37: 
edouard@37: Synopsis:
edouard@37: 
edouard@37:     ./rebuild_docker.sh [build directory]
edouard@37: 
edouard@37: 
edouard@37: Source and Build Volumes :
edouard@37:  
edouard@37:  Role             | Docker Volume     | Host path in example | Rationale
edouard@37: ------------------|-------------------|----------------------|------------------------------------------------
edouard@120:  source directory | /home/runner/src   | ~/src                | Always relative to CWD : "../"
edouard@120:  build directory  | /home/runner/build | ~/build              | First argument to rebuild_docker.sh or ~/build
edouard@37: 
edouard@37: 'build directory' can be specified as absolute path argument of rebuild_docker.sh.
edouard@37: If not specified it defaults to ~/build
edouard@37: 
edouard@37: ```
edouard@37: #!sh
edouard@37: ./rebuild_docker.sh ~/build_next
edouard@37: ```
edouard@37: 
edouard@37: Note: 'build directory' is created if not already existing.
edouard@37: 
edouard@37: ### Build Windows Installer ###
edouard@37: 
edouard@37: The script [build_in_docker.sh](build_in_docker.sh) is used for that purpose.
edouard@37: 
edouard@37: ```
edouard@37: #!sh
edouard@37: ./build_in_docker.sh 
edouard@37: ```
edouard@37: 
edouard@37: Note: 'build directory' must exist before calling build_in_docker.sh, otherwise
edouard@37: Docker will create it as root user. Be sure to create it again if you delete it.
edouard@37: 
edouard@89: Resulting installer is Beremiz-${timestamp}.exe in 'build directory'. 
edouard@37: 
edouard@80: ### Manhole ###
edouard@37: 
edouard@37: Once Docker image ready, the scripts [enter_docker.sh](enter_docker.sh) and
edouard@37: [enter_docker_as_root.sh](enter_docker_as_root.sh) let you issue build 
edouard@37: commands, or install additional packages.
edouard@37: 
edouard@37: [clean_docker_container.sh](clean_docker_container.sh) and [create_docker_container.sh](create_docker_container.sh) and 
edouard@37: [clean_docker_image.sh](clean_docker_image.sh) and [build_docker_image.sh](build_docker_image.sh) are invoked by 
edouard@37: [rebuild_docker.sh](rebuild_docker.sh). 
edouard@80: 
edouard@80: ## Snap Package Build ##
edouard@80: 
edouard@80: 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.
edouard@80: 
edouard@80: Reasons for this are :
edouard@80:  - no parameters or conditional variables exist to tell snapcraft.yaml where to get the source from
edouard@80:  - building from local source should be always possible
edouard@123:  - revisions.txt must be updated in any case so that it is always possible to know what version was used to build resulting package
edouard@80:  - 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.
edouard@80: 
edouard@80: In the end, instead of just calling `snapcraft` to get a snap package, it is more complicated:
edouard@80: 
edouard@80: ```
edouard@123: # assuming source repositories are cloned in ~/src 
edouard@123: # and build happens in ~/build
edouard@123: 
edouard@80: cd ~/build
edouard@80: make -f ~/src/beremiz_public_dist/Makefile DIST=snap
edouard@80: 
edouard@80: ```
edouard@89: Resulting snap package is sources/beremiz_${version}_${platform}.snap.
edouard@89: It can be installed this way:
edouard@80: 
edouard@89: ```
edouard@123: sudo snap install sources/beremiz_1.4-beta2_amd64.snap --dangerous --devmode
edouard@89: ```
edouard@89: