Add documentation converted from old Trac wiki pages

[project/luci.git] / documentation / LAR.md

diff --git a/documentation/LAR.md b/documentation/LAR.md
new file mode 100644 (file)
index 0000000..f44d8dc
--- /dev/null
+++ b/documentation/LAR.md
@@ -0,0 +1,87 @@
+LAR is a simple archive format to pack multiple lua source files and arbitary other resources into a single file.
+
+
+# Format Specification
+
+A LAR archive file is divided into two parts: the payload and the index lookup table.
+All segments of the archive are 4 Byte aligned to ease reading and processing of the format.
+All integers are stored in network byte order, so an implementation has to use htonl() and htons() to properly read them.
+
+Schema:
+       
+       <payload:
+         <member:
+           <N*4 bytes: path of file #1>
+           <N*4 bytes: data of file #1>
+         >
+         
+         <member:
+           <N*4 bytes: path of file #2>
+           <N*4 bytes: data of file #2>
+         >
+       
+         ...
+       
+         <member:
+           <N*4 bytes: path of file #N>
+           <N*4 bytes: data of file #N>
+         >
+       >
+       
+       <index table:
+         <entry:
+           <uint32: offset for path of file #1> <uint32: length for path of file #1>
+           <uint32: offset for data of file #1> <uint32: length for data of file #1>
+           <uint16: type of file #1> <uint16: flags of file #1>
+         >
+       
+         <entry:
+           <uint32: offset for path of file #2> <uint32: length for path of file #2>
+           <uint32: offset for data of file #2> <uint32: length for data of file #2>
+           <uint16: type of file #2> <uint16: flags of file #2>
+         >
+       
+         ...
+       
+         <entry:
+           <uint32: offset for path of file #N> <uint32: length for path of file #N>
+           <uint32: offset for data of file #N> <uint32: length for data of file #N>
+           <uint16: type of file #N> <uint16: flags of file #N>
+         >
+       >
+       
+       <uint32: offset for begin of index table>
+       
+
+
+# Processing
+
+In order to process an LAR archive, an implementation would have to do the following steps:
+
+## Read Index
+
+1. Locate and open the archive file
+1. Seek to end of file - 4 bytes
+1. Read 32bit index offset and swap from network to native byte order
+1. Seek to index offset, calculate index length: filesize - index offset - 4
+1. Initialize a linked list for index table entries
+1. Read each index entry until the index length is reached, read and byteswap 4 * 32bit int and 2 * 16bit int
+1. Seek to begin of file
+
+## Read Member
+
+1. Read the archive index
+1. Iterate through the linked index list, perform the following steps for each entry
+1. Seek to the specified file path offset
+1. Read as much bytes as specified in the file path length into a buffer
+1. Compare the contents of the buffer against the path of the searched member
+1. If buffer and searched path are equal, seek to the specified file data offset
+1. Read data until the file data length is reached, return
+1. Select the next index table entry and repeat from step 3, if there is no next entry then return
+
+# Reference implementation
+
+A reference implementation can be found here:
+http://luci.subsignal.org/trac/browser/luci/trunk/contrib/lar
+
+The lar.pl script is a simple packer for LAR archives and cli.c provides a utility to list and dump packed LAR archives.