Convert rst files to markdown

docs/design/conf.py

@@ -33,6 +33,7 @@
     'sphinx.ext.coverage',
     'sphinx.ext.mathjax',
     'sphinx.ext.ifconfig',
+    'myst_parser',
               # For now, do not use the githubpages extension
               # because the machines that run our buildbots do
               # not have this package installed
@@ -45,8 +46,9 @@
 # The suffix(es) of source filenames.
 # You can specify multiple suffix as a list of string:
 #
-# source_suffix = ['.rst', '.md']
-source_suffix = '.rst'
+# source_suffix = ['.md']
+source_suffix = '.md'
+myst_enable_extensions = ['colon_fence', 'deflist']
 
 # The master toctree document.
 master_doc = 'index'
@@ -71,7 +73,7 @@
 #
 # This is also used if you do content translation via gettext catalogs.
 # Usually you set "language" from the command line for these cases.
-language = None
+language = 'en'
 
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.

docs/design/documentation/MemoryAreaRegionFragment.rst → docs/design/documentation/MemoryAreaRegionFragment.md

@@ -1,11 +1,11 @@
-Memory Area Region Fragment
-============================
+# Memory Area Region Fragment
 
-.. contents::
-   :local:
+```{contents}
+:local: true
+```
+
+## Information
 
-Information
------------------
 All input files that are placed on command line (scripts, archives and
 relocatables), have actual code/data and ELF specific structures. The actual
 code/data is stored as a RegionFragment in ELD. This fragment has a member
@@ -20,42 +20,42 @@ waste of memory to keep the raw data throughtout the linking process.
 A more efficient representation of the RegionFragment will help reduce
 linking large code bases.
 
-Option
---------
+## Option
+
 We will have an option called -Om that will reduce the memory usage due to
 input read only raw data.
 
 By default, this option is disabled.
 
-Replacing raw data
------------------------
+## Replacing raw data
 
 By default the RegionFragment has an llvm::StringRef as member variable carrying
 the raw data.
 We can replace this with MemoryArea and abstract out if the raw data is kept on
-file or in memory. The interface  MemoryArea::request will use llvm::MemoryBuffer::getFile
+file or in memory. The interface MemoryArea::request will use llvm::MemoryBuffer::getFile
 to open file seek a position for access by the caller.
 If the memory is in-memory, the operation should be a simple return of a StringRef.
 
-API/class changes:
--------------------
-  RegionFragment:
-  Region fragment will have a pointer to a MemoryArea instead of a StringRef.
-
-  RegionFragment::getRegion:
-  This will either return a StringRef or do a request and return a StringRef
-  from newly created memory buffer based on -Om option.
-
-  MemoryArea:
-  The class will contain filename, offset in file where the region begins,
-  the size of region and a flag indicating if this area represents a file
-  or it is an "in memory" entity such as linker scripts created on the fly
-  with defsym options.
-
-  MemoryArea::request:
-  API will open file and seek at offset in file + offset within region
-  supplied as parameter, create a StringRef of the same and return it.
+## API/class changes:
+
+> RegionFragment:
+> Region fragment will have a pointer to a MemoryArea instead of a StringRef.
+>
+> RegionFragment::getRegion:
+> This will either return a StringRef or do a request and return a StringRef
+> from newly created memory buffer based on -Om option.
+>
+> MemoryArea:
+> The class will contain filename, offset in file where the region begins,
+> the size of region and a flag indicating if this area represents a file
+> or it is an "in memory" entity such as linker scripts created on the fly
+> with defsym options.
+>
+> MemoryArea::request:
+> API will open file and seek at offset in file + offset within region
+> supplied as parameter, create a StringRef of the same and return it.
+
+## Future Enhancement(s)
+
+> We could use a user provided list of files to keep cached in memory.
 
-Future Enhancement(s)
----------------------
-  We could use a user provided list of files to keep cached in memory.

docs/design/documentation/mergingSimilarStrings.rst → docs/design/documentation/mergingSimilarStrings.md

@@ -1,13 +1,13 @@
-Merging Similar Strings
-===========================
+# Merging Similar Strings
 
-.. contents::
-   :local:
+```{contents}
+:local: true
+```
+
+## Information
 
-Information
--------------
 When the user uses strings that appear either in output/passed as parameters, they all go in to
-readonly strings. Since it is a string, they are terminated by \0. 
+readonly strings. Since it is a string, they are terminated by 0.
 
 When the user uses constant data values that appear in function calls, they all
 go into readonly merge sections. Since its a data value, they all are associated
@@ -17,8 +17,8 @@ To reduce the output memory foot print, they all need to be de-duped.
 
 This mode would be disabled during Partial Linking.
 
-Option
---------
+## Option
+
 We will have an option called -Os thats associated with the linker, the merge
 strings option would be automatically turned on when the user uses this option.
 
@@ -27,40 +27,38 @@ merge option will be disabled as part of that as well.
 
 By default, the merge option is disabled.
 
-Handling AM Sections
------------------------
+## Handling AM Sections
 
 When the Linker needs to handle the AM section, they need to be split into
 multiple fragments defined by the Entry Size of the section.
 
 Each fragment is associated with a symbol, and that is merged similar to how
 debug strings are merged.
 
-The tricky part is to fix the relocations. 
+The tricky part is to fix the relocations.
 
-Handling AMS Sections
------------------------
+## Handling AMS Sections
 
 When the Linker needs to handle the AMS section, they need to be split into
-multiple fragments by looking at individual strings, that are terminated by \0.
+multiple fragments by looking at individual strings, that are terminated by 0.
 
 Each fragment is associated with a symbol, and that is merged similar to how
 debug strings are merged.
 
-Relocations
--------------
+## Relocations
+
 The relocations that are created would need to know how the individual fragments
 are split.
 
 To fix the relocation so that its associated with a proper fragment, the
 relocation offset and the addend information has to be modified so that they
-point to 
+point to
 
-a) The fragments when they have been split
-b) Suffix/Prefix of the data thats used when the relocation is applied to the 'AM' section
+1. The fragments when they have been split
+2. Suffix/Prefix of the data thats used when the relocation is applied to the 'AM' section
 
+## Diagnostics
 
-Diagnostics
----------------
 We need to print diagnostics on how many bytes were merged, and how much was
-saved. 
+saved.
+

docs/design/index.md

@@ -0,0 +1,20 @@
+% eld documentation
+
+# ELD Design Guide
+
+This document describes design details of ELD
+
+```{eval-rst}
+.. toctree::
+   :maxdepth: 2
+
+   documentation/mergingSimilarStrings.md
+   documentation/MemoryAreaRegionFragment.md
+```
+
+## Indices and tables
+
+- {ref}`genindex`
+- {ref}`modindex`
+- {ref}`search`
+

docs/userguide/CMakeLists.txt

@@ -42,7 +42,7 @@ if(LLVM_ENABLE_SPHINX)
         ${LINKER_OPTS_DUMP_DIR}/${target}LinkerOptionsTblGenDump.json
       DEPENDS eld-linkeroptions-create-json-dump-dir)
 
-    # Generates ${target}LinkerOptions restructureText documentation from the
+    # Generates ${target}LinkerOptions Markdown documentation from the
     # ${target}LinkerOptions JSON dump file.
     set(SKIP_OPTION "")
     if(NOT target MATCHES "Gnu")
@@ -54,7 +54,7 @@ if(LLVM_ENABLE_SPHINX)
       COMMAND
         python3 ${CMAKE_CURRENT_SOURCE_DIR}/GenerateOptionsDocsFromTblGen.py
         ${LINKER_OPTS_DUMP_DIR}/${target}LinkerOptionsTblGenDump.json -o
-        ${DOCS_BUILD_SOURCE}/documentation/options/${target}LinkerOptions.rst
+        ${DOCS_BUILD_SOURCE}/documentation/options/${target}LinkerOptions.md
         ${SKIP_OPTION}
         -S ${OPTIONS_SUPPLEMENTS_DIR})
 
@@ -125,6 +125,7 @@ if(LLVM_ENABLE_SPHINX)
     add_custom_command(
       OUTPUT ${ELD_USERGUIDE_PDF} ${ELD_USERGUIDE_HTML_PDF}
       COMMAND
+        ${CMAKE_COMMAND} -E env --unset=PYTHONPATH
         ${Python3_EXECUTABLE}
         ${CMAKE_CURRENT_SOURCE_DIR}/GenerateTypstPDF.py
         ${ELD_USERGUIDE_SINGLEHTML_DIR}/index.html ${ELD_USERGUIDE_TYPST}

docs/userguide/CommandLineOptionsSupplements/remap-inputs-file.md.in

@@ -0,0 +1,12 @@
+Read remap rules from `<file>`.
+
+Each non-empty line in the file is one rule in either format:
+
+- `pattern=replacement`
+- `pattern replacement`
+
+Lines beginning with `#` and blank lines are ignored. Inline `#` comments
+are also supported.
+
+Rules from this file are appended to the same ordered remap list used by
+{option}`--remap-inputs`.

docs/userguide/CommandLineOptionsSupplements/remap-inputs.md.in

@@ -0,0 +1,16 @@
+Rules are evaluated in command-line order; the first matching rule wins.
+The pattern supports wildcard matching.
+
+Example:
+
+- `--remap-inputs=foo.o=bar.o`
+- `--remap-inputs=*foo.o=build/alt/bar.o`
+
+Remapping is applied before path search/open, including linker-script
+`INPUT(...)`, `GROUP(...)`, and `INCLUDE` processing.
+
+How to tell remapping is active:
+
+- `--verbose` prints: `Remapping input file <old> to <new>`.
+- Text map output (`-MapStyle txt`) annotates remapped entries with
+  `# remapped from <original-name>`.

docs/userguide/CommandLineOptionsSupplements/sysroot.md.in

@@ -0,0 +1,20 @@
+- `INPUT(file, file, ...)`
+- `GROUP(file, file, ...)`
+
+The files specified using the INPUT and GROUP command are searched inside the sysroot when:
+
+- The file begins with the `/` character, and
+- The script containing the INPUT/GROUP command is located within the sysroot directory.
+
+Additionally, paths in INPUT/GROUP commands or on the command line can explicitly
+force sysroot expansion by using the `=` or `$SYSROOT` prefix:
+
+- `=/path/to/file` expands to `<sysroot>/path/to/file`
+- `$SYSROOT/path/to/file` expands to `<sysroot>/path/to/file`
+
+This works for both linker script commands and command-line input files.
+If no sysroot is configured, the prefix is stripped and the remaining path is used.
+
+{option}`-L` `<search_directory>`
+
+When `<search_directory>` is prefixed with `=`, then `=` is expanded to the sysroot.