{"id":20892722,"url":"https://github.com/chichunchen/cross-indexing","last_synced_at":"2026-04-15T22:35:26.294Z","repository":{"id":83883799,"uuid":"108149502","full_name":"chichunchen/cross-indexing","owner":"chichunchen","description":"Visualizing and cross referencing the source code of C and Assembly code as web pages with friendly UI.","archived":false,"fork":false,"pushed_at":"2018-12-21T20:59:53.000Z","size":50,"stargazers_count":2,"open_issues_count":0,"forks_count":0,"subscribers_count":4,"default_branch":"master","last_synced_at":"2025-01-19T11:43:32.469Z","etag":null,"topics":["assembly","c","index-generator","ruby"],"latest_commit_sha":null,"homepage":"","language":"Ruby","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/chichunchen.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"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}},"created_at":"2017-10-24T15:50:14.000Z","updated_at":"2024-01-13T23:57:25.000Z","dependencies_parsed_at":"2023-03-10T17:45:35.252Z","dependency_job_id":null,"html_url":"https://github.com/chichunchen/cross-indexing","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chichunchen%2Fcross-indexing","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chichunchen%2Fcross-indexing/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chichunchen%2Fcross-indexing/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chichunchen%2Fcross-indexing/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/chichunchen","download_url":"https://codeload.github.com/chichunchen/cross-indexing/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":243277501,"owners_count":20265352,"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":["assembly","c","index-generator","ruby"],"created_at":"2024-11-18T10:13:46.837Z","updated_at":"2025-12-28T02:22:30.253Z","avatar_url":"https://github.com/chichunchen.png","language":"Ruby","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Cross-Indexing\nVisualizing and cross referencing the source code of C and Assembly code as web pages with friendly UI.\n\n## Features\n- Translate all source code to corresponding html file\n\t- bar.c -\u003e bar.c.html\n\t- foo.c -\u003e foo.c.html\n- The application works well on visualizing non-trivial applications such as [picoc](https://gitlab.com/zsaleeba/picoc), a C interpreter.\n- Support all the optimization flag in gcc (O1, O2, O3, Os).\n\n## How to run\n```\nmake\nruby xref.rb a.out\n```\n\n## Result\n- Referene C and Assembly using O3 flag\n![](https://i.imgur.com/msh7wrq.png)\n- Reference function from header\n![](https://i.imgur.com/iNeEPor.png)\n- Result of referencing [picoc](https://gitlab.com/zsaleeba/picoc)\n\t- When testing with `picoc`, we can jump to different .html files by clicking links if the called function is declared in another file.\n![](https://i.imgur.com/ZUAuxQJ.png)\n\t- Content of one of the file \n![](https://i.imgur.com/hvKKq7W.png)\n\n## TODO\n    - [X] objdump, dwarfdump information extraction\n    - [X] Convert the source code to HTML, with side-by-side assembly and source, and with embedded branch-target links. \n    - [X] Place the HTML file(s) into a subdirectory named HTML, with an extra file index.html that contains a link to the main HTML file(s), a location-specific link to the beginning of the code for main, and information about when and where the xref tool was run. \n    - [X] About \"assembly centric\": display assembly-language instructions, in **address order**, and show **next to** them the corresponding source.\n    - [X] Subtles: `-O2`, `-O3` cases testing; static function with same name in different files.\n    - [ ] About beautifying: the source line may appear more than once on your web page.  For the sake of clarity, you should print the second and subsequent occurrences in a **grayed-out color**. **Vertical white space** should be inserted as needed to make the alignment work out.\n\n## Docs\n\n### dwarfdump.rb\n\n- DwarfDecode class\n    - Parses all the information we need in .debug_info and .debug_line\n    - The picoc example is too large, and a single scan on the whole dwarfdump output costs too much time. So we divide them into several parts per filename.\n    - @global_var : hash {filename =\u003e Variable instances} \n    - @line_info  : hash {filename =\u003e content}\n        - each element of content is: hash {real_address =\u003e [lineno, \"ET\", uri's filename(str)]}\n        - if not ET or no uri, the element is `nil`.\n    - @functions  : hash {filename =\u003e Function instances}\n    - @subroutine : has  {filename =\u003e Subroutine content}\n        - each element of subroutine content is: {:local_addr =\u003e 0x.. :low_pc =\u003e 0x.., high_pc =\u003e dec, call_file =\u003e \\*.c|h, call_line =\u003e 0x..}\n    - @min_lno    : hash {filename =\u003e minimum lineno (int)}\n    - @intervals  : hash {filename =\u003e [low_addr(int), high_addr(int)]}\n        - There are some lineno that cannot be matched. So store address instead and judge the range of address.\n    - @lexical    : hash {filename =\u003e {lowpc =\u003e highpc}} \n    - @lexical_rev: hash {filename =\u003e {highpc =\u003e lowpc}}\n        - These two give us reference for jumps in loops\n    - @name2file  : hash {function name =\u003e filename}\n        - Static functions are recognized and not stored here\n        - This can help eniminate useless href links.\n\n- Function class\n    - @local_addr : 0x????????\n    - @type       : including void, static, etc\n    - @decl_file\n    - @lineno\n    - @low_pc     : real address(hex) that matches objdump info.\n    - @high_pc    : a dec number to be added to low_pc\n    - @name\n    - @params     : list of Variable\n    - @inner_var\n        - The format is like: [..., [[...], [...]], [..., [..., [...]]]].\n        - Each [] is like a {} in C code, the sequence is the same as in the C code.\n        - Stored elements are Variable instances.\n\n- Variable class\n    - @local_addr : 0x????????\n    - @name\n    - @decl_file  : the whole filename where the variable is declared.\n    - @lineno     : hex value of line number\n    - @type       : list of type names\n        - last one is base_type name, such as \"int\", \"char\"\n        - second last is \"base\"\n        - others are like \"array\", \"pointer\", \"const\".\n\n- dig_type(adress, whole_code)\n    - This function recursively generates the name of a type, given the local address.\n    - Currently support all base types, pointer, array, and other types with format `/DW_TAG_[a-z]+_type/`\n    - Get stuck when faced with `typedef`, so in our testing, we just leave an empty dig_type function.\n\n\n### objump.rb\n- This file define a `Objdump` class\n\t- Take the file name of executable as parameter\n\t- Private class in `Objdump` class\n\t\t- Instruction\n\t\t\t- Attributes\n\t\t\t\t- address\n\t\t\t\t- assembly code\n\t\t\t\t- name of function\n\t\t\t- `Objdump` can use all of the attributes in `Instruction` class\n\t- Expose `functions`, `instructsions`, and `instructions_hash` for read-only.\n\t\t- functions\n\t\t\t- hash\n\t\t\t\t- key: name of the function in objdump\n\t\t\t\t- value:\n\t\t\t\t\t- A list of `Instruction` object.\n\t\t- instructions\n\t\t\t- An array of instructions\n\t\t\t\t- Each element contains address of the instruction and code of the instruction\n\t\t\t- The array is for driving the assembly-centric output using `sort_by `\n\t\t\t\t- `@instructions.sort_by! { |obj| obj[:addr] }`\n\t\t- instructions_hash\n\t\t\t- key\n\t\t\t\t- Address of instruction\n\t\t\t- value\n\t\t\t\t- `{ :code =\u003e assebmly_code, :func =\u003e name_of_function }`\n\t- Methods\n\t\t- getInstructionsByRange(start_addr, end_addr)\n\t\t\t- return an array of instructions window that contains all the instructions from start_addr to end_addr-1\n\t\t\t- This method is mostly used by printing instructions in `xref.rb`\n\n### xref.rb\n- This file define a `CrossIndex` class, which is also the driver of A4.\n\t- Public Methods:\n\t\t- sourceToHTML\n\t\t\t- If HTML folder does not exists\n\t\t\t\t- create a HTML folder\n\t\t\t- If HTML folder exists\n\t\t\t\t- rm -rf HTML\n\t\t\t\t- create a new HTML folder\n\t\t\t- Produce all web pages and put all of them into HTML/\n\t\t\t- Produce index.html into HTML/\n\t- Nontrivial private Methods:\n\t\t- writeSource\n\t\t\t- Write C source into web page using a range of source line number.\n\t\t\t- endFlag\n\t\t\t\t- Decide whether print out the remaing instruction.\n\t\t\t- repeatFlag\n\t\t\t\t- Grey the c source block if repeatFlag is set.\n\t\t- writeInstruction\n\t\t\t- Write instruction to web page using given start and end assembly address\n\t\t\t- Use endFlag to deal with outputing the remaining instructions in the function that the address in range[0]. \n\t\t\t- If the instruction contains fixed address, then output its link\n\t\t- writeHTMLBody\n\t\t\t- Print the whole source and assembly with assembly centric\n\t\t- htmlEncoding\n\t\t\t- Escape `\u0026, \u003c, \u003e`\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fchichunchen%2Fcross-indexing","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fchichunchen%2Fcross-indexing","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fchichunchen%2Fcross-indexing/lists"}