Why having such a structure ?

"Yes, why having such a (complicated) structure ?" you ask, humble visitor... Current jalv2 compiler version cannot handle include statements in sub-directories, so this is a legitimate question.

We, the jallib team, decided to have such a structure because

• having files organized helps finding them. Visitors may only want to download a few files, or search for a specific library. A structured repository helps.
• as a developer, as a committer, it's not reasonable to put all files into a single place. That would be a mess. And developers don't like entropy. It also helps classifying things, and when you classify things, you have a better understanding of the overall picture. A structured repository is mandatory

Description

Now let's dive into this !

Note: what is described here starts from the SVN /trunk.

Just a map, to understand how low/high we are during this trip.

               ┌────────────────────────────────┐
       high    │            external            │
               ├────────────────┬───────────────┤
        │      │   peripheral   │    jal        │      
               ├────────────────┴───────────────┤
       low     │         device   files         │   
               └────────────────────────────────┘

casualities

casualities contains libraries and samples which were aimed to be included in jallib, but fall here because they're just not working, are not compilable, have no maintainer, are orphans... You may want to have a look here, maybe you'll find the lib you want. But be aware you'll probably have to modify it a lot. And if it works, please report ! We'll be very pleased to include it back into the appropriate directory.

include/sample

• include: contains libraries which can be included. That is, librairies...
• sample: contains by_device, where you'll find many samples for each PIC, and test, which are used to produce samples (this is more for internal use, for developpers).

Now, in the followings, we'll talk about structure within the include section.

include

device

Ah... device ! Have you ever wondered how many PICs are handled in jallib ? Is your shiny-but-weird PIC supported ? Go here, you'll find the answer, amongst ~300 hundreds of device files !

Device files are the very base of every program, you'll find more on this page, section "Device File". Device files are the lower level of jallib, if you want, you can only use them to create your program (but you'll miss the power of all other jallib libraries).

peripheral

In this directory, you'll find every library used to handle PICs' peripherals. Peripherals is the term Microchip uses to describe PIC's features. These libraries belongs the core. It's a higher level than device files, but still low level.

You'll find here everything to play with: adc, comparator, data_eeprom, flash_memory, i2c, pwm, spi, timer, usart.

jal

jal section is quite special. This is not about the compiler, no, it's about jal language extensions, that is functionalities you'd like to see as built-ins, implemented into the compiler, for everyday/common usage. These are core too. It gets jalv2 even to higher level !

You'll find here libraries to produce delays, to print and format messages, and many more.

external

This is the highest level... This is where you'll find dedicated librarie for specific parts. It's named external because it's about everything that's not internal, that's not within a PIC.

You'll find here libraries to play with LCDs, keyboards, motors, sensors, memory, etc...

sample

This section contains samples. Every samples are prefixed by PIC's name, so you should be able to easily get all samples for your favorite PIC.

These samples are ready-to-compile, so fell free to give a try, it's easy ! If you created a new sample, don't hesitate, share your shiny new sample to the jallib group, we'll be pleased to add it to the repository.

test

In the "test" map, you'll find quite the same hierarchy as in "include". This is where remain test files. Test files are chip independent (there's no "include 16fxxxx"), and perform heavy tests on several important libraries (mainly core libraries, PIC-specific).

So, for instance, in test/peripheral/usart, you'll find test dedidated to USART libraries. These tests are mixed up with a "board" file (from "board" directory). A board file and a test file gives a functional, compilable piece of code, which will perform the selected test on the selected target, using the selected board.

"Woah" I hear you say... "What is it such complicated ?" It's not complicated. At least, this apparent complexity avoid code duplication, and permits to seperate the test logic, from the board/target chip setup. Each type of file focus on a specific task. Don't worry about all of this: unless you plan to contribute to jallib as a developper, you won't need all of these. But... we'd be please if you help :)

unittest

A sub-section is about unittesting. You'll find files containing tests you can run using jallib script: jallib unittest <testfile>.

Unittesting is performed using PICShell libraries, files are being annotated with some special tags (like @assertEquals ...). These tests can be run in PC-silico, and does not require a PIC. There are here to tests some libraries and compiler's features, ensuring there's no regression.