________________________________________________________________________________

libctrelf

Copyright 2016 Gabriel Marcano
________________________________________________________________________________


--------------------------------------------------------------------------------
Licensing
--------------------------------------------------------------------------------

This project is licensed under the GPL 2 or later licenses, at your choice.
Refer to COPYING for more licensing information and for the licensing for the
code borrowed from other sources.


--------------------------------------------------------------------------------
About
--------------------------------------------------------------------------------

This library is meant to be a collection of functions to simplify reading ELF
files.

Note this library is still in active development and the API is not considered
stable. Breaking changes will be mentioned in commits at the very least.


--------------------------------------------------------------------------------
Dependencies
--------------------------------------------------------------------------------

 - Autotools in general. These are used to create the build scripts.

--------------------------------------------------------------------------------
Compiling
--------------------------------------------------------------------------------

The Autotools setup assumes that devkitarm is already in the PATH.

 # this following line is if the 3ds compiler isn't in the path
 export PATH=${PATH}:${DEVKITPRO}/bin:${DEVKITARM}/bin
 autoreconf -if
 ./configure --host arm-none-eabi --prefix=[lib install path]
 make

Example:
  export PATH=${PATH}:${DEVKITPRO}/bin:${DEVKITARM}/bin
  autoreconf -if
  ./configure --host arm-none-eabi --prefix="$HOME/.local/usr/arm-none-eabi-9/"
  make -j10


--------------------------------------------------------------------------------
Installation
--------------------------------------------------------------------------------

TBD. This library is built using Autotools, so it supports the 'make install'
and 'make uninstall' targets. Be sure to set --prefix when calling configure
if either of the preceeding targets will be used, else by default the generated
Makefile will install to /usr/local/ (most likely)) !

Example (after having compiled):
  #this will install to the directory specified in prefix, or /usr/local/ if
  #prefix isn't defined (most likely)!
  make install


--------------------------------------------------------------------------------
Usage
--------------------------------------------------------------------------------

Depending on where the library is installed, one may need to use -L in one's
projects to point the compiler to find the library, then use -lctrelf to cause
the linker to link in the static library.

Example:
  arm-none-eabi-gcc -I$HOME/.local/usr/arm-none-eabi-9/include \
    -L$HOME/.local/usr/arm-none-eabi-9/lib -Os -Wall -Wextra -Wpedantic hello.c\
    -lctrelf

One setup that is recommended is to export a variable such as, CTRARM9, to point
to the root of the prefix where libctr9 is installed. This way, it is easier to
point to the lib and include directories (such as by using $CTRARM9/include and
$CTRARM9/lib).


--------------------------------------------------------------------------------
Documentation (TODO)
--------------------------------------------------------------------------------

This project uses Doxygen markup in order to facilitate the generation of
documentation, which should be found when generated in the doc/ folder. Each
header in the include/ directory should also be well documented and can be used
as reference for programming.

In addition, some documentation is hosted in GitHub pages:
	https://gemarcano.github.io/ctrelf/


--------------------------------------------------------------------------------
Testing (TODO)
--------------------------------------------------------------------------------

This project does include a homegrown unit testing framework and some unit tests
for this library. See the test/ directory for more information. Note that the
unit testing payload WILL write to NAND (in theory writes to areas that are
unused) as a part of unit testing.

To compile it, change directory to test/, then execute `make test`. The
generated test.bin is an A9LH compatible binary.


--------------------------------------------------------------------------------
Issues/Bugs
--------------------------------------------------------------------------------

Please report these to the issue tracker at the repository, and these will be
addressed as soon as possible, if not at least acknowledged. The more detailed
the reports, the more likely they are to be addressed quickly. In particular,
the following information can be quite useful when debugging bugs:

 - Type of 2/3DS system
 - Operating system being used to compile
 - Release/commit of library in use
 - Steps to reproduce issue
 - Expected behavior
 - Actual behavior
 - ARM9 entry point
 - Any modifications to the library, or extensions


--------------------------------------------------------------------------------
Contributing
--------------------------------------------------------------------------------

Pull requests are welcome. All requests will be looked at in detail, and must be
documented in a similar fashion as the rest of the code for this project. In
particular, it is unlikely (but not impossible) that code that emmits warnings
with the warnings in use by this library would be merged without first fixing/
addressing what is causing the warnings to be emitted.


--------------------------------------------------------------------------------
Credits
--------------------------------------------------------------------------------

 - #3dshacks @ Rizon for starting me on my path to 3DS homebrew development
 - #Cakey @ Freenode for the continued development support
 - #3dsdev @ EFNet for the occasional help answering questions
 - dark_samus for helping to develop A9LH stuff in Cakey, which drove for the
    development of this library
 - Delebile for publishing the public arm9loaderhax implementation, making using
    and testing this library possible (or less of a pain)
 - Aurora, et. al (you know who you are, I hope) for for general development
    help and brainstorming