Add guide for importing LUFA into an AS5/AS6 project.

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
  */

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 <b><code>make export_tar</code></b> from the command line. This will generate two .TAR files in the
+ *  current directory, named <b>LUFA_<i>{Version Number}</i>.tar</b> and
+ *  <b>LUFA_<i>{Version Number}</i>_Code_Templates.tar</b>. 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
+ */