diff --git a/LUFA.pnproj b/LUFA.pnproj index ee9de0e6e6..0b2307ec6c 100644 --- a/LUFA.pnproj +++ b/LUFA.pnproj @@ -1 +1 @@ - \ No newline at end of file + \ No newline at end of file diff --git a/LUFA/DoxygenPages/DevelopingWithLUFA.txt b/LUFA/DoxygenPages/DevelopingWithLUFA.txt index 4ea379938c..6dc851a2a4 100644 --- a/LUFA/DoxygenPages/DevelopingWithLUFA.txt +++ b/LUFA/DoxygenPages/DevelopingWithLUFA.txt @@ -15,6 +15,7 @@ * \li \subpage Page_Migration - Migrating from an Older LUFA Version * \li \subpage Page_VIDPID - Allocated USB VID and PID Values * \li \subpage Page_BuildLibrary - Building as a Linkable Library + * \li \subpage Page_ExportingLibrary - Exporting LUFA for IDE Use * \li \subpage Page_WritingBoardDrivers - How to Write Custom Board Drivers * \li \subpage Page_SoftwareBootloaderStart - How to jump to the bootloader in software */ diff --git a/LUFA/DoxygenPages/ExportingLibrary.txt b/LUFA/DoxygenPages/ExportingLibrary.txt new file mode 100644 index 0000000000..848c42b984 --- /dev/null +++ b/LUFA/DoxygenPages/ExportingLibrary.txt @@ -0,0 +1,106 @@ +/** \file + * + * This file contains special DoxyGen information for the generation of the main page and other special + * documentation pages. It is not a project source file. + */ + +/** \page Page_ExportingLibrary Exporting the Library for IDE Use + * + * While LUFA was designed to allow for easy compilation in a makefile driven environment, + * it is possible to export the library into a form suitable for drop-in use inside of an + * IDE. + * + * \section Sec_LibraryExport Exporting the Library + * An export of the library is at its most basic, a direct copy of the main "LUFA" source folder from the + * root download folder; this contains the library core which can be re-used within external projects. + * However, as many IDEs attempt to automatically compile all included source files, it is neccesary to + * exclude some directories and files from the library core export to allow for easier integration into + * an IDE project. + * + * \subsection SSec_ManualExport Manual Export + * To manually export the library core, copy over the main LUFA library folder from the LUFA root directory, + * renaming as desired. Within the library core folder, the following directories should be removed or + * excluded from your IDE import: + * - Documentation/ + * - DoxygenPages/ + * - CodeTemplates/ + * + * If required, files from the CodeTemplates/ subdirectory may be copied to your IDE project as required. + * + * The resulting copy of the library may then be imported into your chosen IDE according to the instructions + * shown in \ref Sec_LibraryImport. + * + * \subsection SSec_AutomaticExport Automatic Export + * If desired, the steps indicated in \ref SSec_ManualExport may be automatically performed, by running the + * command make export_tar from the command line. This will generate two .TAR files in the + * current directory, named LUFA_{Version Number}.tar and + * LUFA_{Version Number}_Code_Templates.tar. The first archive contains the exported LUFA core + * with the non-required files removed, while the second contains an archived copy of the code template files + * for the current LUFA version. + * + * The resulting archived copy of the library may then be extracted to your chosen IDE project source directory + * and imported according to the instructions shown in \ref Sec_LibraryImport. + * + * \section Sec_LibraryImport Importing the Library + * An exported copy of the library may be imported wholesale into an IDE project, if the instructions detailed + * in \ref Sec_LibraryExport are followed. + * + * Specific instructions for importing an exported version of LUFA into various IDEs are listed below. + * + * \subsection SSec_AS56_Import Importing into AVRStudio 5/Atmel Studio 6 + * To import LUFA into a new or existing project, the following steps must be followed. + * + * \subsubsection SSSec_AS56_Import_Step1 Copy over the exported library + * Copy over the exported library archive created via the steps listed in \ref Sec_LibraryExport to your AS5/AS6 + * project directory. + * + * \image html Images\AS5_AS6_Import\AS5_AS6_Import_Step1.png + * + * \subsubsection SSSec_AS56_Import_Step2 Extract exported library + * Extract out the contents of the archive to a new folder. This may be any name you wish, however keep in mind + * that this name will need to be referenced within your user application under most circumstances. It is + * suggested that this folder be named "LUFA", or "LUFA" followed by the version string for easy reference. + * + * \image html Images\AS5_AS6_Import\AS5_AS6_Import_Step2.png + * + * \subsubsection SSSec_AS56_Import_Step3 Add the library files + * Open your AVRStudio 5/Atmel Studio 6 project. From the "Solution Explorer" pane, click the "Show All Files" + * button on the toolbar to display ghosted icons of files and folders located in the project source directory + * that are not currently added to the project. + * + * \image html Images\AS5_AS6_Import\AS5_AS6_Import_Step3.png + * + * Right-click the ghosted version of the extracted LUFA export folder in the Solution Explorer pane, and + * choose the "Add to Project" option from the context menu. This will add the entire LUFA source tree to the + * current project. + * + * \subsubsection SSSec_AS56_Import_Step4 Open Project Toolchain Properties + * In the Solution Explorer pane, click the project node, and press the "Properties" button in the toolbar to + * open the Project Properties window. This window allows you to configure the various project global compiler, + * assembler and linker options. + * + * \image html Images\AS5_AS6_Import\AS5_AS6_Import_Step4.png + * + * Click the "Toolchain" tab on the left side of the Project Properties window. + * + * \subsubsection SSSec_AS56_Import_Step5 Configure Project Toolchain Properties + * + * In the GNU C Compiler section, open the "Symbols" page. Click the "Add Item" button to the top-right of the + * "Defined Symbols" section to add new symbols. + * + * At a minimum, you will need to define the following symbols (for more information on these symbols, see + * \ref Page_ConfiguringApps): + * - ARCH + * - F_CPU + * - F_USB + * - BOARD + * \image html Images\AS5_AS6_Import\AS5_AS6_Import_Step5_1.png + * + * Next, open the GNU C Compiler section's "Optimization" page. Ensure that the option to prepare functions for + * garbage collection is enabled. + * \image html Images\AS5_AS6_Import\AS5_AS6_Import_Step5_2.png + * + * Finally, in the GNU C Linker section, open the "Optimization" page. Ensure that the option to garbage collect + * unused sections is selected. + * \image html Images\AS5_AS6_Import\AS5_AS6_Import_Step5_3.png + */ diff --git a/LUFA/DoxygenPages/Images/AS5_AS6_Import/AS5_AS6_Import_Step1.png b/LUFA/DoxygenPages/Images/AS5_AS6_Import/AS5_AS6_Import_Step1.png new file mode 100644 index 0000000000..4f0c26f374 Binary files /dev/null and b/LUFA/DoxygenPages/Images/AS5_AS6_Import/AS5_AS6_Import_Step1.png differ diff --git a/LUFA/DoxygenPages/Images/AS5_AS6_Import/AS5_AS6_Import_Step2.png b/LUFA/DoxygenPages/Images/AS5_AS6_Import/AS5_AS6_Import_Step2.png new file mode 100644 index 0000000000..6e309ae415 Binary files /dev/null and b/LUFA/DoxygenPages/Images/AS5_AS6_Import/AS5_AS6_Import_Step2.png differ diff --git a/LUFA/DoxygenPages/Images/AS5_AS6_Import/AS5_AS6_Import_Step3.png b/LUFA/DoxygenPages/Images/AS5_AS6_Import/AS5_AS6_Import_Step3.png new file mode 100644 index 0000000000..8192c9ae8a Binary files /dev/null and b/LUFA/DoxygenPages/Images/AS5_AS6_Import/AS5_AS6_Import_Step3.png differ diff --git a/LUFA/DoxygenPages/Images/AS5_AS6_Import/AS5_AS6_Import_Step4.png b/LUFA/DoxygenPages/Images/AS5_AS6_Import/AS5_AS6_Import_Step4.png new file mode 100644 index 0000000000..2bb8f5fc8f Binary files /dev/null and b/LUFA/DoxygenPages/Images/AS5_AS6_Import/AS5_AS6_Import_Step4.png differ diff --git a/LUFA/DoxygenPages/Images/AS5_AS6_Import/AS5_AS6_Import_Step5_1.png b/LUFA/DoxygenPages/Images/AS5_AS6_Import/AS5_AS6_Import_Step5_1.png new file mode 100644 index 0000000000..f3a49ba9c4 Binary files /dev/null and b/LUFA/DoxygenPages/Images/AS5_AS6_Import/AS5_AS6_Import_Step5_1.png differ diff --git a/LUFA/DoxygenPages/Images/AS5_AS6_Import/AS5_AS6_Import_Step5_2.png b/LUFA/DoxygenPages/Images/AS5_AS6_Import/AS5_AS6_Import_Step5_2.png new file mode 100644 index 0000000000..078f4ec8d7 Binary files /dev/null and b/LUFA/DoxygenPages/Images/AS5_AS6_Import/AS5_AS6_Import_Step5_2.png differ diff --git a/LUFA/DoxygenPages/Images/AS5_AS6_Import/AS5_AS6_Import_Step5_3.png b/LUFA/DoxygenPages/Images/AS5_AS6_Import/AS5_AS6_Import_Step5_3.png new file mode 100644 index 0000000000..8a8571bd86 Binary files /dev/null and b/LUFA/DoxygenPages/Images/AS5_AS6_Import/AS5_AS6_Import_Step5_3.png differ