]> git.gir.st - tmk_keyboard.git/blob - protocol/lufa/LUFA-120730/LUFA/DoxygenPages/ExportingLibrary.txt
Squashed 'tmk_core/' changes from b9e0ea0..caca2c0
[tmk_keyboard.git] / protocol / lufa / LUFA-120730 / LUFA / DoxygenPages / ExportingLibrary.txt
1 /** \file
2 *
3 * This file contains special DoxyGen information for the generation of the main page and other special
4 * documentation pages. It is not a project source file.
5 */
6
7 /** \page Page_ExportingLibrary Exporting the Library for IDE Use
8 *
9 * While LUFA was designed to allow for easy compilation in a makefile driven environment,
10 * it is possible to export the library into a form suitable for drop-in use inside of an
11 * IDE.
12 *
13 * \section Sec_LibraryExport Exporting the Library
14 * An export of the library is at its most basic, a direct copy of the main "LUFA" source folder from the
15 * root download folder; this contains the library core which can be re-used within external projects.
16 * However, as many IDEs attempt to automatically compile all included source files, it is neccesary to
17 * exclude some directories and files from the library core export to allow for easier integration into
18 * an IDE project.
19 *
20 * \subsection SSec_ManualExport Manual Export
21 * To manually export the library core, copy over the main LUFA library folder from the LUFA root directory,
22 * renaming as desired. Within the library core folder, the following directories should be removed or
23 * excluded from your IDE import:
24 * - Documentation/
25 * - DoxygenPages/
26 * - CodeTemplates/
27 *
28 * If required, files from the CodeTemplates/ subdirectory may be copied to your IDE project as needed.
29 *
30 * The resulting copy of the library may then be imported into your chosen IDE according to the instructions
31 * shown in \ref Sec_LibraryImport.
32 *
33 * \subsection SSec_AutomaticExport Automatic Export
34 * If desired, the steps indicated in \ref SSec_ManualExport may be automatically performed, by running the
35 * command <b><code>make export_tar</code></b> from the command line. This will generate two .tar files in the
36 * current directory, named <code>LUFA_YYMMDD.tar</code> and <code>LUFA_YYMMDD_Code_Templates.tar</code> (where
37 * "YYMMDD" is the version of the library being exported). The first archive contains the exported LUFA core
38 * with the non-required files removed, while the second contains an archived copy of the code template files
39 * for the current LUFA version.
40 *
41 * The resulting archived copy of the library may then be extracted to your chosen IDE project source directory
42 * and imported according to the instructions shown in \ref Sec_LibraryImport.
43 *
44 * \section Sec_LibraryImport Importing the Library
45 * An exported copy of the library may be imported wholesale into an IDE project, if the instructions detailed
46 * in \ref Sec_LibraryExport are followed.
47 *
48 * Specific instructions for importing an exported version of LUFA into various IDEs are listed below.
49 *
50 * \subsection SSec_AS56_Import Importing into AVRStudio 5/Atmel Studio 6
51 * To import LUFA into a new or existing project, the following steps must be followed.
52 *
53 * \subsubsection SSSec_AS56_Import_Step1 Copy over the exported library
54 * Copy over the exported library archive created via the steps listed in \ref Sec_LibraryExport to your AS5/AS6
55 * project directory.
56 *
57 * \image html Images/AS5_AS6_Import/AS5_AS6_Import_Step1.png
58 *
59 * \subsubsection SSSec_AS56_Import_Step2 Extract exported library
60 * Extract out the contents of the archive to a new folder. This may be any name you wish, however keep in mind
61 * that this name will need to be referenced within your user application under most circumstances. It is
62 * suggested that this folder be named "LUFA", or "LUFA" followed by the version string for easy reference.
63 *
64 * \image html Images/AS5_AS6_Import/AS5_AS6_Import_Step2.png
65 *
66 * \subsubsection SSSec_AS56_Import_Step3 Add the library files
67 * Open your AVRStudio 5/Atmel Studio 6 project. From the "Solution Explorer" pane, click the "Show All Files"
68 * button on the toolbar to display ghosted icons of files and folders located in the project source directory
69 * that are not currently added to the project.
70 *
71 * \image html Images/AS5_AS6_Import/AS5_AS6_Import_Step3.png
72 *
73 * Right-click the ghosted version of the extracted LUFA export folder in the Solution Explorer pane, and
74 * choose the "Add to Project" option from the context menu. This will add the entire LUFA source tree to the
75 * current project.
76 *
77 * \subsubsection SSSec_AS56_Import_Step4 Open Project Toolchain Properties
78 * In the Solution Explorer pane, click the project node, and press the "Properties" button in the toolbar to
79 * open the Project Properties window. This window allows you to configure the various project global compiler,
80 * assembler and linker options.
81 *
82 * \image html Images/AS5_AS6_Import/AS5_AS6_Import_Step4.png
83 *
84 * Click the "Toolchain" tab on the left side of the Project Properties window.
85 *
86 * \subsubsection SSSec_AS56_Import_Step5 Configure Project Toolchain Properties
87 *
88 * In the GNU C Compiler section, open the "Symbols" page. Click the "Add Item" button to the top-right of the
89 * "Defined Symbols" section to add new symbols.
90 *
91 * At a minimum, you will need to define the following symbols (for more information on these symbols, see
92 * \ref Page_ConfiguringApps):
93 * - ARCH
94 * - F_CPU
95 * - F_USB
96 * - BOARD
97 * \image html Images/AS5_AS6_Import/AS5_AS6_Import_Step5_1.png
98 *
99 * Next, open the GNU C Compiler section's "Optimization" page. Ensure that the option to prepare functions for
100 * garbage collection is enabled.
101 * \image html Images/AS5_AS6_Import/AS5_AS6_Import_Step5_2.png
102 *
103 * Finally, in the GNU C Linker section, open the "Optimization" page. Ensure that the option to garbage collect
104 * unused sections is selected.
105 * \image html Images/AS5_AS6_Import/AS5_AS6_Import_Step5_3.png
106 */
Imprint / Impressum