The information on this page is no longer entirely accurate. Builds are handled in the cloud via conda-forge, and standalone binaries are no longer distributed.

====== Binary Distribution ======

 !GitHub webhooks are setup to send notifications to blake. Blake forwards those to three build machines. Currently, webhooks are being listened to only on Linux. Linux runs the server that drives the Jenkins jobs.


===== Jenkins Setup =====


Jenkins server runs on Linux, Jenkins agents on Linux, Mac and Windows. The server instance manages Jenkins, the agents run the jobs.

 1. On Linux, to start Jenkins, run command:<code>
docker stop jenkins-master

docker rm jenkins-master

docker run -d -u root --name jenkins-master -p 8080:8080 -p 50000:50000 --restart unless-stopped -v /home/eman2/jenkins_home:/var/jenkins_home -e PLUGINS_FORCE_UPGRADE=true -e TRY_UPGRADE_IF_NO_MARKER=true --restart unless-stopped jenkins/jenkins:lts

</code>

 2. Server login info: 10.10.11.176:8080/ username: eman2
 3. Install Java on agents.
 4. Setup passwordless ssh connections from Linux server to agents.
 5. Binary builds require conda-build and constructor. Packaging is done with <code>constructor</code>, a tool for making installers from conda packages.
 6. Nodes: http://10.10.11.176:8080/computer/
  7. http://10.10.11.176:8080/computer/linux/configure
    8. name: linux
    9. remoteFS: /home/eman2/linux-1-agent/
    10. numExecutors: 100
    11. host: eman-centos7-01
    12. credentialsId: jenkins-key-eman2
    13. label: eman
    14. envVars
     15. DEPLOY_PATH: /opt/web2py_apps/web2py/applications/cryoem/static/software/
     16. HOME_DIR: /home/eman2
     17. PATH+EXTRA: /home/eman2/miniconda3/bin

  18. http://10.10.11.176:8080/computer/mac/configure
    19. name: mac
    20. remoteFS: /Users/eman/mac-1-agent
    21. numExecutors: 100
    22. host: eman-macmini
    23. credentialsId: jenkins-key-eman
    24. label: eman
    25. envVars
     26. DEPLOY_PATH: /opt/web2py_apps/web2py/applications/cryoem/static/software/
     27. HOME_DIR: /Users/eman/
     28. PATH+EXTRA: /Users/eman/miniconda3/bin

  29. http://10.10.11.176:8080/computer/win/configure
    30. name: win
    31. remoteFS: D:\workspace\win-1-agent
    32. numExecutors: 100
    33. host: BM-WIN-01
    34. credentialsId: jenkins-key-eman
    35. !JavaPath: "D:\Downloads\openjdk-11+28_windows-x64_bin\jdk-11\bin\java.exe"
    36. Prefix Start Agent Command: "D: &&"
    37. label: eman
    38. envVars
     39. DEPLOY_PATH: /opt/web2py_apps/web2py/applications/cryoem/static/software/
     40. HOME_DIR: D:
     41. PATH+EXTRA: D:\Miniconda3;D:\Miniconda3\Scripts
    42. On Windows for sh calls in jenkins to work "Git for Windows" might need to be installed.

==== Jenkins Server Setup (on Linux) ====
 43. http://10.10.11.176:8080/manage/configure
  44. Labels: main master
  45. Jenkins URL: http://10.10.11.176:8080/
  46. System Admin e-mail address: eman-bot (linux)<eman.github@gmail.com>
  47. SSH Servers
   48.  Name: Installer-Server
   49.  Hostname: cryoem.bcm.edu
   50.  Username: eman-binary-uploader
   51.  Remote Directory: /opt/web2py_apps/web2py/applications/cryoem/static/software/

 52. http://10.10.11.176:8080/manage/configureSecurity/
  53. Agents
   54. TCP port for inbound agents
    55. Fixed: 50000
  56. Git Host Key Verification Configuration
   57. Host Key Verification Strategy
    58. Known hosts file

 59. Credentials: http://10.10.11.176:8080/manage/credentials/ 
  <code>
ID                  Name
gh-eman-bot         eman-bot (gh-eman-
jenkins-key-eman    eman (jenkins-key-eman)
jenkins-key-eman2   eman2 (jenkins-key-eman2)
</code>

 60. Jobs
  61. http://10.10.11.176:8080/job/cryoem-eman2-trigger/: Triggers job cryoem-eman2 on agents
  62. http://10.10.11.176:8080/job/cryoem-eman2/: Test(?) and binary builds
    * eman-dev(?): Triggers new build of eman-dev
  63. http://10.10.11.176:8080/job/eman-bump-version/
  64. http://10.10.11.176:8080/job/eman-feedstock-update-version/
  65. http://10.10.11.176:8080/job/eman-feedstock-trigger-from-eman-master/
  66. http://10.10.11.176:8080/job/build-binary/
  67. http://10.10.11.176:8080/job/build-binary-trigger/
  68. http://10.10.11.176:8080/job/eman-feedstock-building-eman-v2.99/

 69. JenkinsCI: [[https://github.com/cryoem/eman2/blob/master/Jenkinsfile|Jenkinsfile]]
   70. Secrets like ssh keys are stored locally in Jenkins
   71. Manually triggered by including "[ci build]" anywhere in the last commit message. Manually triggered builds on master branch are uploaded as [[https://cryoem.bcm.edu/downloads/view_eman2_version/25|continuous builds]] and builds triggered from any other branch are uploaded to [[https://cryoem.bcm.edu/downloads/view_eman2_version/26|testing area]].
   72. Any branch in the form of "release-" triggers continuous builds without having to include "[ci build]" in the commit message. Once the release branch is ready, release binaries are manually copied from cont. builds folder into the release folder on the server.


<code>#!wiki comment

Mac: slave clock sync https://blog.shameerc.com/2017/03/quick-tip-fixing-time-drift-issue-on-docker-for-mac docker run --rm --privileged alpine hwclock -s

Windows: 
OPENGL: https://github.com/conda/conda-recipes/blob/master/qt5/notes.md


Not sure if this is true
 73. Jenkins master needs PATH prepended with $CONDA_PREFIX/bin
</code>



====== Anaconda ======

Dependencies not available on anaconda or conda-forge are available on [[https://anaconda.org/cryoem/|cryoem]]. The binaries are built and uploaded using [[https://conda-forge.org/|conda-forge's]] [[https://github.com/conda-forge/conda-smithy|conda-smithy]]. [[https://github.com/conda-forge/conda-smithy|conda-smithy]] takes care of generating feedstocks, registering them on !GitHub and online CI services and building conda recipes. 


 74. [[https://github.com/conda/conda|conda]] is the package manager.
 75. https://anaconda.org is the online repository of binaries.
 76. [[https://github.com/conda/conda-build|conda-build]] is the tool to build from source.
 77. [[https://github.com/cryoem/constructor.git|constructor]] is the tool to package eman2 and dependency binaries into a single installer file.

EMAN2 is distributed as a single installer which includes all its dependencies. 

===== Conda =====

Packages that are available on https://anaconda.org can be installed into any conda environment by issuing the command <code>conda install <package></code>. Conda installs the package along with its dependencies. In order for packages to benefit from this automation, they need to be packaged in a specific way. That can be done with <code>conda-build</code>. <code>conda-build</code> builds packages according to instructions provided in a <code>recipe</code>. A recipe consists of a file with package metadata, <code>meta.yaml</code>, and any other necessary resources like build scripts, (<code>build.sh</code>, <code>bld.bat</code>), patches and so on.

===== Recipes, Feedstocks and anaconda.org channel: cryoem =====

Most of EMAN2 dependencies can be found on anaconda's channels, <code>defaults</code> and <code>conda-forge</code>. A few that do not exist or need to be customized have been built and uploaded to channel [[https://anaconda.org/cryoem/dashboard|cryoem]]. The recipes are hosted in separate repositories on [[https://github.com/cryoem/|GitHub]]. Every recipe repository follows the feedstock approach of [[http://conda-forge.github.io/|conda-forge]]. See [[https://github.com/cryoem?utf8=%E2%9C%93&q=-feedstock&type=&language=|here]] for a complete list.



===== Feedstocks =====
  * https://github.com/cryoem/eman-deps-feedstock
  * https://github.com/cryoem/pydusa-feedstock
  * https://github.com/cryoem/eman-feedstock

==== General instructions ====
 78. Existing feedstocks
 79. Files to edit: recipe/, conda-build.yaml, conda-forge.yaml
 80. conda create -n smithy conda-smithy -c conda-forge
 81. conda-smithy rerender
 82. More info in conda-smithy/README.md, conda smithy -h, conda-forge.org/docs
 83. New feedstocks
 84. conda-smithy/README.md, conda smithy -h

==== Conda-smithy Workflow ====

Conda smithy uses tokens to authenticate with !GitHub.

Conda-smithy commands:
 <code>#!highlight bash
conda create -n smithy conda-smithy
conda activate smithy
conda smithy init <recipe_directory>
conda smithy register-github <feedstock_directory> --organization cryoem
conda smithy register-ci --organization cryoem --without-azure --without-drone
conda smithy rerender --no-check-uptodate
</code>







====== Build System Notes ======


===== CMake =====

 85. //libpython// can be linked statically or dynamically when python is built. It is important for python extensions to be aware of the type of linking in order to avoid segfaults. This can be accomplished by querying Py_ENABLE_SHARED.

 <code>#!highlight bash
python -c "import sysconfig; print(sysconfig.get_config_var('Py_ENABLE_SHARED'))"
</code>

 In EMAN, it is done in [[https://github.com/cryoem/eman2/blob/master/cmake/FindPython.cmake#L29-L73|cmake/FindPython.cmake]]

 86. OpenGL detection when Anaconda's compilers are used is done using a [[https://github.com/cryoem/eman2/blob/master/recipe/cross-linux.cmake|cmake toolchain file]].

 87. glext.h file needed for OpenGL related module compilation is already present on Linux and Mac. On Windows, it is manually copied once into C:\Program Files\Microsoft SDKs\Windows\v6.0A\Include\gl. On Appveyor it is downloaded as part of env setup every time a test is run.


<code>{#!wiki comment

=== Docker ===
Docker images and helper scripts are at --(https://github.com/cryoem/docker-images )-- https://github.com/cryoem/build-scripts.

Command to run docker with GUI support, CentOS7: <code>
xhost + local:root

docker run -it -v /tmp/.X11-unix:/tmp/.X11-unix -e DISPLAY=unix$DISPLAY cryoem/eman-nvidia-cuda8-centos7

# When done with eman
xhost - local:root
</code>

:FIXME: Runs as root on Linux. `chown` doesn't work, the resulting installer has root ownership.
</code>}