{ "info": { "author": "Google LLC", "author_email": "", "bugtrack_url": null, "classifiers": [ "License :: OSI Approved :: Apache Software License", "Operating System :: OS Independent", "Programming Language :: Python :: 3.6", "Programming Language :: Python :: 3.7" ], "description": "# ELFHex\n\n [![Build Status](https://travis-ci.org/Synook/elfhex.svg?branch=master)](https://travis-ci.org/Synook/elfhex) [![Coverage Status](https://coveralls.io/repos/github/Synook/elfhex/badge.svg?branch=master)](https://coveralls.io/github/Synook/elfhex?branch=master)\n\nThis is not an officially supported Google product.\n\nELFHex is a simple \"assembler\" designed for learning machine code. It takes programs comprising machine instructions and packages them into simple 32-bit ELF executable binaries. It aims to do the minimum amount of transformation necessary to keep the output binaries understandable and easy to relate back to the source files. Nevertheless, it has several language features (beyond just constructing the ELF header) to make it more convenient than just trying to write an executable using a hex editor.\n\n## Usage\n\nELFHex requires at least Python 3.6. To install the package, run:\n\n```shell\npip install elfhex\n```\n\nThis installs a command-line tool named `elfhex`. View its usage with `elfhex -h`. In general, the tool needs an input source file and a location for the output executable. Other options include the ability to omit the ELF header in the output, and set the starting memory address and entry point label.\n\n### Development\n\nThis project uses Python 3.6 and `pipenv`. In order to install dependencies, run `pipenv install --dev`. The program can then be run using `python -m elfhex`. To execute the tests, run `pytest`.\n\nThere are some pre-commit hooks that check for certain formatting and other issues, which can be installed using `pre-commit install`. Run [`black .`](https://black.readthedocs.io/en/stable/) to auto-format changes, and `flake8` to check for PEP 8 violations.\n\nTo build a package, first generate `requirements.txt`, and then use `setuptools` to build the distributable artifacts.\n\n```shell\npipenv run pipenv_to_requirements\npipenv run python setup.py sdist bdist_wheel\n```\n\n### As a module\n\nThe ELFHex module can also be imported. The command-line tool's usage of it can be seen in `__main__.py`. In general, there are separate components that deal with preprocessing, transformation, rendering, and the ELF header.\n\n```python\nimport elfhex\nfile_loader = elfhex.FileLoader(include_paths)\npreprocessor = elfhex.Preprocessor(file_loader)\npreprocessed = preprocessor.preprocess(input_path, max_fragment_depth)\nprogram = elfhex.Transformer().transform(preprocessed)\nheader = elfhex.elf.get_header(entry_label)\nprogram.prepend_header_to_first_segment(header)\noutput = program.render(memory_start)\n```\n\n## Language reference\n\nSource files are written in `.eh` format. Each EH file comprises the *program declaration*, *includes* of other source files, *segments*, corresponding to segments in the output ELF file, and *fragments*, which can be copied into segment code. Each segment has a name, various arguments, and contents.\n\n```\nprogram 3 < 4096 # program declaration\n\ninclude \"file.eh\" # segments will be merged by name\ninclude fragments \"some/file.eh\" # only fragments will be included\n\nsegment segment_name(flags: rx) {\n 1e e7 =10d4 \"string\" # bytes, numbers, and strings\n [label] <