{"id":13435267,"url":"https://github.com/happi/theBeamBook","last_synced_at":"2025-03-18T02:31:34.680Z","repository":{"id":19628926,"uuid":"85983888","full_name":"happi/theBeamBook","owner":"happi","description":"A description of the Erlang Runtime System ERTS and the virtual Machine BEAM.","archived":false,"fork":false,"pushed_at":"2025-03-13T07:53:41.000Z","size":3656,"stargazers_count":3170,"open_issues_count":6,"forks_count":225,"subscribers_count":158,"default_branch":"master","last_synced_at":"2025-03-13T08:01:51.839Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Erlang","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"cc-by-4.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/happi.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":"FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null},"funding":{"github":["happihacking"]}},"created_at":"2017-03-23T18:25:31.000Z","updated_at":"2025-03-13T07:53:41.000Z","dependencies_parsed_at":"2023-01-11T20:31:49.844Z","dependency_job_id":"de5867a6-6462-46cd-bfc4-df4663d718e8","html_url":"https://github.com/happi/theBeamBook","commit_stats":{"total_commits":259,"total_committers":54,"mean_commits":4.796296296296297,"dds":0.7490347490347491,"last_synced_commit":"5ce6f4b4654a1dcc4ae423fd296f2f335ba1f7f2"},"previous_names":[],"tags_count":21,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/happi%2FtheBeamBook","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/happi%2FtheBeamBook/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/happi%2FtheBeamBook/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/happi%2FtheBeamBook/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/happi","download_url":"https://codeload.github.com/happi/theBeamBook/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":244144024,"owners_count":20405323,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-07-31T03:00:34.375Z","updated_at":"2025-03-18T02:31:34.671Z","avatar_url":"https://github.com/happi.png","language":"Erlang","funding_links":["https://github.com/sponsors/happihacking"],"categories":["Erlang","Books","Learning","杂项"],"sub_categories":["YAML","Books"],"readme":"![PDF Build](https://github.com/happi/theBeamBook/actions/workflows/build.yml/badge.svg)\n![Pages Build](https://github.com/happi/theBeamBook/actions/workflows/gh-pages.yml/badge.svg) \n\n# The BEAM Book\n\nThis is an attempt to document the internals of the Erlang runtime\nsystem and the Erlang virtual machine known as the BEAM.\n\nYou can read or download the book as a PDF from the [latest\nstable release](https://github.com/happi/theBeamBook/releases/latest)\nor [online as a webpage](https://happi.github.io/theBeamBook/).\n\nThe book is written in AsciiDoc and most of it can be read directly\nfrom source on GitHub in your browser. To read the book online just\nopen the file [book.asciidoc](book.asciidoc).\n\nYou can also read it as an [Github IO page](https://happi.github.io/theBeamBook/).\n\n## Contributing\n\nThe plan is to make this book project into a collaboration effort so\nthat we can get a complete documentation of the Erlang runtime system\nas soon as possible. Please feel free to contribute since this work is\nfar from done.\n\nYou can contribute by raising an issue, comment on open issues\nor create a branch with a fix or an addition.\n\nNote that the book is released under a Creative Commons license (see below)\nand anything you contribute will also be included under that license.\n\nThe chapters in the book can be in one of four states:\n\n1. Placeholder, basically only the title and perhaps an outline of the\nchapter is done. If you are interested in writing the chapter or parts\nof the chapter grab the corresponding issue and start writing.\n2. First draft, most of the text is in place but more editing is needed.\nFeel free to comment, focusing on missing content, hard to read passages,\nthe order of sections within the chapter, diagrams or pictures needed,\nand plain errors.\n3. Final draft, spelling and other errors probably still need fixing.\n4. Done (for OTP version X), if things changes in later versions of\nErlang OTP the chapter will need an update.\n\n(Not all chapters are yet marked in this way.)\n\n### Style guide\n\nThere are several ways to use AsciiDoc and some constructs work\nbetter in some environments or for some targets.\n\nThe priority of the AsciiDoc code in this project is that it\nrenders nicely for the following targets in the following order:\n1. The PDF target\n2. The HTML target\n3. View directly on GitHub\n\nWe will try to come up with specific guides for which AsciiDoc\nconstructs to use and add them here as we discover what works\nand what doesn't work.\n\n\u003c!-- #### The AsciiDoc dialect to use --\u003e\n\n#### Comments in AsciiDoc\nEach chapter should begin with a comment about the status of\nthe chapter. This should be one of 'Placeholder', 'First Draft',\n'Final Draft', or 'Done (for Erlang X.X)'.\nThere can also be a link to an issue describing what is needed\nto bring the chapter to the next level.\n\nA comment in the code starts with '//'.\n\n\u003c!-- #### Callouts\n     What type of callout to use and for what (note, warning etc.)\n\n--\u003e\n\n#### Linking to OTP/Erlang source code\n\nWhen referring to the source code of Erlang/OTP please add\na link to a tagged version (not to master) of the code on GitHub,\nas in:\n\n----\n\u003cpre\u003e\n link:https://github.com/erlang/otp/blob/OTP-19.1/erts/emulator/beam/erl_time.h[erl_time.h]\n\u003c/pre\u003e\n----\n\n#### Directory structure and build\n\nTry to keep the root directory clean.\n\nPut each chapter in a separate .asciidoc file in the chapters directory.\nUse underscores \"_\" to separate words in chapter names but try to use\njust one-word file names for the chapters.\n\nPut code used in a chapter in code/CHAPTERNAME_chapter/src, and add an\ninclude of the code in ap-code_listings.asciidoc.\n\nPut images in the images directory.\n\n#### How to tag chapters, sections, figures\n\nThe following is not yet done consistently so please feel\nfree to contribute by fixing tags in the current version.\n\nChapter tags should start with 'CH-'. Words in a tag are separated by\nunderscores '_'.\n\nPart tags should start with 'P-'.\n\nSection tags should start with 'SEC-'.\n\nFigure tags should start with 'FIG-'.\n\nAppendix tags should start with 'AP-'.\n\nCode listing tags (in the appendix) should start with 'LISTING-'.\n\n### Process\n\nIf you find something you do not understand or which is incorrect\nplease raise an issue in the [issue tracker](https://github.com/happi/theBeamBook/issues).\n\nIf you find spelling or formatting errors feel free to fix them and\njust make a pull request.\n\nFor larger rewrites check the status of the chapter and check the\nissues to see if someone is likely to be working on that chapter\nright now. If someone else is working on the chapter try to contact\nthat person before doing a major rewrite. Otherwise either just go\nahead and do the rewrite and do a pull request or start by opening\nan issue declaring what you intend to do.\n\n\n## Building the PDF locally from source\n\nThe project contains a Makefile which\nwill let you build your own PDF from the source, provided\nthat you have all the needed tools installed. Just running\nthe command\n```shell\nmake\n```\nwill build the file `beam-book.pdf` in the top directory\nas well as the HTML version under the `site` directory.\n\nWe assume that you already have an Erlang installation of\nyour choice for running examples etc. Apart from that, see\nbelow for what you need in order to build the book.\n\n### Docker\n\nYou can build the project locally via Docker without having to\ninstall any addtional software, by first building the docker\n image. Assuming you have Docker installed, run:\n```shell\nmake docker-build\n```\nAnd then you can build the book by running\n```shell\nmake docker\n```\n(Note: On Linux, the resulting files will be created with\nUser ID 1000, regardless of what your current user ID is\noutside Docker. This is due to how Docker integrates with\nthe file system.)\n\n#### Devcontainers in the IDE\n\nIf you use VSCode or any other editor that has support for\nDevcontainers, this repository contains a configuration that\ncan be used out of the box. By opening the project in the dev\ncontainer, you get a shell inside the container with all the\ntools pre-installed and with access to the project files so\nthat all you need to do is run `make`.\n\nFor a tutorial on devcontainers, see\n[Introduction to Dev Containers](https://happihacking.com/blog/posts/2023/dev-containers/),\n[Decvontainer setup](https://happihacking.com/blog/posts/2023/dev-containers-emacs/),\nand [Devcontainers, UIDs and file permissions](https://happihacking.com/blog/posts/2024/dev-containers-uids/).\n\nIf you prefer to build natively rather than use Docker,\nsee the following sections depending on your system.\n\n### Linux\n\nThe following should work on a Debian based system, such as Ubuntu:\n1. `apt install git rsync wget curl make`\n1. `apt install ruby ruby-dev default-jre`\n1. `apt install asciidoctor graphviz`\n1. `gem install asciidoctor-pdf asciidoctor-diagram rouge`\n1. `make`\n\n### Mac OSX\n\n#### Using Homebrew\n\n1. `brew install asciidoctor graphviz wget ditaa`\n1. `gem install asciidoctor-pdf asciidoctor-diagram rouge`\n1. `make`\n\n#### Manual installation\n\n1. Install [asciidoc](https://github.com/asciidoctor/asciidoctor)\n1. Install [asciidoctor-pdf](https://github.com/asciidoctor/asciidoctor-pdf)\n1. Install [asciidoctor-diagram](http://asciidoctor.org/docs/asciidoctor-diagram/)\n1. Install [ditaa](https://github.com/stathissideris/ditaa)\n1. Install [graphviz](https://www.graphviz.org/)\n1. Install [rouge](https://asciidoctor.org/docs/user-manual/#rouge)\n1. Install [wget](https://www.gnu.org/software/wget/)\n1. `make`\n\n## License\n\n_The Erlang Runtime System_ by Erik Stenman is licensed under a\nCreative Commons Attribution 4.0 International License. Based on a\nwork at https://github.com/happi/theBeamBook.\nA complete copy of the license can be found [here](LICENSE).\n\n\n# A short and personal history of the book\n\nI, Erik Stenman (Happi), started writing this book back in 2013.\nAt first I was thinking of self publishing the book on my blog,\nbut since English isn't my native language I felt I needed help\nby a good editor.\n\nI managed to get a deal with O'Reilly and started converting my\noutline to their build process. My original plan was for a very long\nand thorough book, which the editor felt would get few readers. I\nstarted cutting my content and tried to write more of a tutorial than\na manual. Unfortunately progress was slow and pre-sales was even\nslower and the publisher cancelled the book in 2015.\n\nI managed to get a new deal with Pragmatic and started converting my\ncontent to their build system and rewriting the book according to the\nmore pragmatic style of the new publisher, cutting down the content\neven further. The series editor also wanted me to fit the book into\nthe Elixir series and I tried to add more Elixir examples. I did not\nreally manage to make it into an Elixir book and also my progress was\nstill slow, which led to another cancellation of the book early 2017.\n\nNow I had three repositories with three different book building systems\nwith three different outlines of the book. In the end I more or less\nwent back to the original longer book outline and the original AsciiDoc\nbuild system. I started a new repository in a private GitHub account and\nstarted pulling in content from the three different versions.\n\nThen on April 7 2017 I opened the repository to the public to share it with\nsome students. I didn't think anyone else would notice and I was not\nplanning to release the book for real yet since the repo currently\njust contains bits and pieces from the different versions of the book.\n\nThere was more interest than I had expected though and fortunately\nalso several who where willing to contribute. From now on the book\nis a collaborative effort to document the Erlang runtime system ERTS and the Erlang virtual machine BEAM,\nand it is released with a Creative Commons license (see above).\n\nWatch this space for further news and to see the whole book take shape.\n\n-- Erik Stenman aka Happi\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhappi%2FtheBeamBook","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fhappi%2FtheBeamBook","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhappi%2FtheBeamBook/lists"}