Skip to content

Latest commit

 

History

History
121 lines (85 loc) · 6.85 KB

README.md

File metadata and controls

121 lines (85 loc) · 6.85 KB
Raw

BinaryDoc, Binary code is the best Document

BinaryDoc generates Documents with rich diagrams from Binary files directly for Java.

This docker image needs to work together with mysql database with specified mysql.cnf configurations. An sample docker-compose.yml file has been provided.

Sample Diagrams in Generated documents:

  • Control Flow Graph for Java method bytecode Control Flow Graph for method java.net.Inet6Address.getByAddress

  • UML Sequence Diagram for Java method bytecode UML Sequence Diagram for method java.net.Inet6Address.getByAddress

  • UML Hierarchy Diagram for Java Class UML Hierarchy Diagram for class java.nio.channels.FileChannel UML Hierarchy Diagram for class java.lang.Class UML Hierarchy Diagram for class javax.swing.JTable

  • Dependency Network diagram for Java package Dependency Network Diagram for package java.beans

  • Jar,Jmod files Dependency Network Diagram (sfdp layout) Dependency Network Diagram for OpenJDK 13

There are web sites containing the documentes and diagrams generated by BinaryDoc:

BinaryDoc Docker Compose User Guide

This is an sample docker compose setup for BinaryDoc, which generates Documents with rich diagrams from Binary files directly for Java.

Warning

  • This docker compose setup is designed for none-production environment, better for evaluation or testing box
  • Password is set in .env, while password vault could be used in production
  • Default RAM in mysql.cnf is small, while 128 GB or more RAM is available in production

Hardware Requirement

BinaryDoc is a compute-intensive software which needs powerful hardware.

Here we list the suggested minimal hardware requirements:

  • CPU: 8 or more threads
  • RAM: 24 GB minimal, 64 GB is suggested for better performance, based on the size of the Java application to be parsed
  • Disk type: SSD Drive is suggested, M.2 SSD or NVMe SSD are preferred
  • Disk size: 20 GB or more avialbe disk space is suggested
    • The size is based on the binary data to be parsed.
    • Example: OpenJDK 11 binary data size is 387.9 MB, and the current corresponding DB size is 7 GB.

Steps

Customize the config files

  • .env
    • Change the DB password (default=123456) when needed
    • Change the TCP ports when needed
  • mysql.cnf
    • Change innodb_buffer_pool_size based on avabile RAM hardware and the size of application to be parsed
    • Change innodb_buffer_pool_instances based on parallel workloads

If running Docker on Windows

  • If running on other system, ignore this step
  • Change the file etc/mysql/conf.d/mysql.cnf permission as read only, or else the mysql file will not load it

Start the Docker Instances

  • docker-compose up -d

Run the Parser for current OpenJDK for demo:

  • ./run-parse-demo.sh
    • Note. the parser execution takes about 1 hour on M.2 SSD disk, and needs up to 24 GB RAM

Run the Parser for your application:

  • Put your Java Application to be Parsed to the app-to-parse folder
    • Example: Copy the application .jmod or .jar files to this folder
  • Start the parser

Access the Web Site

(Optional) Access the Backend DB if interested

  • http://127.0.0.1:10190/
    • System: MySQL
    • Server: binarydoc-db
    • Username: root
    • Password: 123456, or the password set in the .env file
    • Database: binarydocjvmadm
  • MySQL Workbench, or Other DB Access Tools
    • Server: localhost
    • Port: 13306

Other commands

When we want to Delete Existing Docker Instances, and to Start over again

When we want login to the Running Docker container

  • sudo docker-compose exec binarydoc /bin/bash

TCP Ports Mapping

  • We may change the ports 10180, 10190, 13306 in .env when necessary

Community