protocol/lufa/LUFA-120730/LUFA/DoxygenPages/ExportingLibrary.txt

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