X-Git-Url: http://git.linex4red.de/pub/USBasp.git/blobdiff_plain/2b43a6d7df6221b979f08326c02eb1cfdd077c49..ba6d9c1a971db3c42bf0b054ebb64f72b3e3ddba:/LUFA/DoxygenPages/BuildSystem.txt diff --git a/LUFA/DoxygenPages/BuildSystem.txt b/LUFA/DoxygenPages/BuildSystem.txt index 564033200..ef57fcf0c 100644 --- a/LUFA/DoxygenPages/BuildSystem.txt +++ b/LUFA/DoxygenPages/BuildSystem.txt @@ -6,607 +6,49 @@ /** \page Page_BuildSystem The LUFA Build System * - * \section Sec_BuildSystemOverview Overview of the LUFA Build System - * The LUFA build system is an attempt at making a set of re-usable, modular build make files which - * can be referenced in a LUFA powered project, to minimize the amount of code required in an - * application makefile. The system is written in GNU Make, and each module is independent of - * one-another. + * \section Sec_BuildSystem_Overview Overview of the LUFA Build System + * The LUFA build system was originally an attempt at making a set of + * re-usable, modular build make files which could be referenced in a LUFA + * powered project, to minimize the amount of code required in an + * application makefile. * - * For details on the prerequisites needed for Linux and Windows machines to be able to use the LUFA - * build system, see \ref Sec_Prerequisites. + * As it turned out to be fairly generic in nature, it was split out into its + * own separate project, called DMBS (Dean's Makefile Build System) + * which is released into the public domain. LUFA-specific portions of the + * LUFA build system extend DMBS, and provide a universal build system for all + * LUFA projects. * - * To use a LUFA build system module, simply add an include to your project makefile. All user projects - * should at a minimum include \ref Page_BuildModule_CORE for base functionality: - * \code - * include $(LUFA_PATH)/Build/lufa_core.mk - * \endcode - * - * Once included in your project makefile, the associated build module targets will be added to your - * project's build makefile targets automatically. To call a build target, run make {TARGET_NAME} - * from the command line, substituting in the appropriate target name. - * - * \see \ref Sec_AppMakefileParams for a copy of the sample LUFA project makefile. - * - * Each build module may have one or more mandatory parameters (GNU Make variables) which must - * be supplied in the project makefile for the module to work, and one or more optional parameters which - * may be defined and which will assume a sensible default if not. - * - * \section SSec_BuildSystemModules Available Modules - * - * The following modules are included in this LUFA release: - * - * \li \subpage Page_BuildModule_ATPROGRAM - Device Programming - * \li \subpage Page_BuildModule_AVRDUDE - Device Programming - * \li \subpage Page_BuildModule_BUILD - Compiling/Assembling/Linking - * \li \subpage Page_BuildModule_CORE - Core Build System Functions - * \li \subpage Page_BuildModule_CPPCHECK - Static Code Analysis - * \li \subpage Page_BuildModule_DFU - Device Programming - * \li \subpage Page_BuildModule_DOXYGEN - Automated Source Code Documentation - * \li \subpage Page_BuildModule_HID - Device Programming - * \li \subpage Page_BuildModule_SOURCES - LUFA Module Source Code Variables - * - * If you have problems building using the LUFA build system, see \subpage Page_BuildTroubleshooting for resolution steps. - */ - - /** \page Page_BuildModule_BUILD The BUILD build module - * - * The BUILD LUFA build system module, providing targets for the compilation, - * assembling and linking of an application from source code into binary files - * suitable for programming into a target device, using the GCC compiler. - * - * To use this module in your application makefile, add the following code: - * \code - * include $(LUFA_PATH)/Build/lufa_build.mk - * \endcode - * - * \section SSec_BuildModule_BUILD_Requirements Requirements - * This module requires the the architecture appropriate binaries of the GCC compiler are available in your - * system's PATH variable. The GCC compiler and associated toolchain is distributed in Atmel AVR Studio - * 5.x and Atmel Studio 6.x installation directories, as well as in many third party distribution packages. - * - * \section SSec_BuildModule_BUILD_Targets Targets - * - *
| size | - *Display size of the compiled application FLASH and SRAM segments. | - *
| symbol-sizes | - *Display a size-sorted list of symbols from the compiled application, in decimal bytes. | - *
| lib | - *Build and archive all source files into a library A binary file. | - *
| all | - *Build and link the application into ELF debug and HEX binary files. | - *
| elf | - *Build and link the application into an ELF debug file. | - *
| hex | - *Build and link the application and produce HEX and EEP binary files. | - *
| lss | - *Build and link the application and produce a LSS source code/assembly code mixed listing file. | - *
| clean | - *Remove all intermediary files and binary output files. | - *
| mostlyclean | - *Remove all intermediary files but preserve any binary output files. | - *
| <filename>.s | - *Create an assembly listing of a given input C/C++ source file. | - *
| TARGET | - *Name of the application output file prefix (e.g. TestApplication). | - *
| ARCH | - *Architecture of the target processor (see \ref Page_DeviceSupport). | - *
| MCU | - *Name of the Atmel processor model (e.g. at90usb1287). | - *
| SRC | - *List of relative or absolute paths to the application C (.c), C++ (.cpp) and Assembly (.S) source files. | - *
| F_USB | - *Speed in Hz of the input clock frequency to the target's USB controller. | - *
| LUFA_PATH | - *Path to the LUFA library core, either relative or absolute (e.g. ../LUFA-000000/LUFA/). | - *
| BOARD | - *LUFA board hardware drivers to use (see \ref Page_DeviceSupport). | - *
| OPTIMIZATION | - *Optimization level to use when compiling source files (see GCC manual). | - *
| C_STANDARD | - *Version of the C standard to apply when compiling C++ source files (see GCC manual). | - *
| CPP_STANDARD | - *Version of the C++ standard to apply when compiling C++ source files (see GCC manual). | - *
| DEBUG_FORMAT | - *Format of the debug information to embed in the generated object files (see GCC manual). | - *
| DEBUG_LEVEL | - *Level of the debugging information to embed in the generated object files (see GCC manual). | - *
| F_CPU | - *Speed of the processor CPU clock, in Hz. | - *
| C_FLAGS | - *Flags to pass to the C compiler only, after the automatically generated flags. | - *
| CPP_FLAGS | - *Flags to pass to the C++ compiler only, after the automatically generated flags. | - *
| ASM_FLAGS | - *Flags to pass to the assembler only, after the automatically generated flags. | - *
| CC_FLAGS | - *Common flags to pass to the C/C++ compiler and assembler, after the automatically generated flags. | - *
| LD_FLAGS | - *Flags to pass to the linker, after the automatically generated flags. | - *
| LINKER_RELAXATIONS | - *Enables or disables linker relaxations when linking the application binary. This can reduce the total size - * of the application by replacing full \c CALL instructions with smaller \c RCALL instructions where possible. - * \note On some unpatched versions of binutils, this can cause link failures in some circumstances. If you - * receive a link error relocation truncated to fit: R_AVR_13_PCREL, disable this setting. | - *
| OBJDIR | - *Directory to place the generated object and dependency files. If set to "." the same folder as the source file will be used. - * \note When this option is enabled, all source filenames must be unique. | - *
| OBJECT_FILES | - *List of additional object files that should be linked into the resulting binary. | - *
| None | - *
| None | - *
| help | - *Display build system help and configuration information. | - *
| list_targets | - *List all available build targets from the build system. | - *
| list_modules | - *List all available build modules from the build system. | - *
| list_mandatory | - *List all mandatory parameters required by the included modules. | - *
| list_optional | - *List all optional parameters required by the included modules. | - *
| list_provided | - *List all variables provided by the included modules. | - *
| list_macros | - *List all macros provided by the included modules. | - *
| None | - *
| None | - *
| None | - *
| None | - *
| atprogram | - *Program the device FLASH memory with the application's executable data. | - *
| atprogram-ee | - *Program the device EEPROM memory with the application's EEPROM data. | - *
| MCU | - *Name of the Atmel processor model (e.g. at90usb1287). | - *
| TARGET | - *Name of the application output file prefix (e.g. TestApplication). | - *
| ATPROGRAM_PROGRAMMER | - *Name of the Atmel programmer or debugger tool to communicate with (e.g. jtagice3). | - *
| ATPROGRAM_INTERFACE | - *Name of the programming interface to use when programming the target (e.g. spi). | - *
| ATPROGRAM_PORT | - *Name of the communication port to use when when programming with a serially connected tool (e.g. COM2). | - *
| None | - *
| None | - *
| avrdude | - *Program the device FLASH memory with the application's executable data. | - *
| avrdude-ee | - *Program the device EEPROM memory with the application's EEPROM data. | - *
| MCU | - *Name of the Atmel processor model (e.g. at90usb1287). | - *
| TARGET | - *Name of the application output file prefix (e.g. TestApplication). | - *
| AVRDUDE_PROGRAMMER | - *Name of the programmer or debugger tool to communicate with (e.g. jtagicemkii). | - *
| AVRDUDE_PORT | - *Name of the communication port to use when when programming with the connected tool (e.g. COM2, /dev/ttyUSB0 or usb). | - *
| AVRDUDE_FLAGS | - *Additional flags to pass to avrdude when programming, applied after the automatically generated flags. | - *
| None | - *
| None | - *
| cppcheck | - *Statically analyze the project source code for issues. | - *
| cppcheck-config | - *Check the cppcheck configuration - scan source code and warn about missing header files and other issues. | - *
| SRC | - *List of source files to statically analyze. | - *
| CPPCHECK_INCLUDES | - *Path of extra directories to check when attemting to resolve C/C++ header file includes. | - *
| CPPCHECK_EXCLUDES | - *Paths or path fragments to exclude when analyzing. | - *
| CPPCHECK_MSG_TEMPLATE | - *Output message template to use when printing errors, warnings and information (see cppcheck documentation). | - *
| CPPCHECK_ENABLE | - *Analysis rule categories to enable (see cppcheck documentation). | - *
| CPPCHECK_SUPPRESS | - *Specific analysis rules to suppress (see cppcheck documentation). | - *
| CPPCHECK_FAIL_ON_WARNING | - *Set to Y to fail the analysis job with an error exit code if warnings are found, N to continue without failing. | - *
| CPPCHECK_QUIET | - *Set to Y to suppress all output except warnings and errors, N to show verbose output information. | - *
| CPPCHECK_FLAGS | - *Extra flags to pass to cppcheck, after the automatically generated flags. | - *
| None | - *
| None | - *
| dfu | - *Program the device FLASH memory with the application's executable data using dfu-programmer. | - *
| dfu-ee | - *Program the device EEPROM memory with the application's EEPROM data using dfu-programmer. | - *
| flip | - *Program the device FLASH memory with the application's executable data using batchisp. | - *
| flip-ee | - *Program the device EEPROM memory with the application's EEPROM data using batchisp. | - *
| MCU | - *Name of the Atmel processor model (e.g. at90usb1287). | - *
| TARGET | - *Name of the application output file prefix (e.g. TestApplication). | - *
| None | - *
| None | - *
| doxygen | - *Generate project documentation. | - *
| doxygen_create | - *Create a new Doxygen configuration file using the latest template. | - *
| doxygen_upgrade | - *Upgrade an existing Doxygen configuration file to the latest template | - *
| LUFA_PATH | *Path to the LUFA library core, either relative or absolute (e.g. ../LUFA-000000/LUFA/). | *
| DOXYGEN_CONF | - *Name and path of the base Doxygen configuration file for the project. | - *
| DOXYGEN_FAIL_ON_WARNING | - *Set to Y to fail the generation with an error exit code if warnings are found other than unsupported configuration parameters, N to continue without failing. | - *
| DOXYGEN_OVERRIDE_PARAMS | - *Extra Doxygen configuration parameters to apply, overriding the corresponding config entry in the project's configuration file (e.g. QUIET=YES). | - *
| None | + *ARCH | + *Architecture of the target processor (see \ref Page_DeviceSupport). | *
| None | *
| hid | - *Program the device FLASH memory with the application's executable data using hid_bootloader_cli. | - *||
| hid-ee | - *Program the device EEPROM memory with the application's EEPROM data using hid_bootloader_cli and - * a temporary AVR application programmed into the target's FLASH. - * \note This will erase the currently loaded application in the target. | - *||
| teensy | - *Program the device FLASH memory with the application's executable data using teensy_loader_cli. | + *LUFA_SRC_USB | + *List of LUFA USB driver source files. | *
| teensy-ee | - *Program the device EEPROM memory with the application's EEPROM data using teensy_loader_cli and - * a temporary AVR application programmed into the target's FLASH. - * \note This will erase the currently loaded application in the target. | + *LUFA_SRC_USBCLASS | + *List of LUFA USB Class driver source files. | *
| MCU | - *Name of the Atmel processor model (e.g. at90usb1287). | + *LUFA_SRC_TEMPERATURE | + *List of LUFA temperature sensor driver source files. | *
| TARGET | - *Name of the application output file prefix (e.g. TestApplication). | + *LUFA_SRC_SERIAL | + *List of LUFA Serial U(S)ART driver source files. | *
| None | + *LUFA_SRC_TWI | + *List of LUFA TWI driver source files. | *
| None | + *LUFA_SRC_PLATFORM | + *List of LUFA architecture specific platform management source files. | *
| LUFA_PATH | *Path to the LUFA library core, either relative or absolute (e.g. ../LUFA-000000/LUFA/). | *
| ARCH | - *Architecture of the target processor (see \ref Page_DeviceSupport). | - *
| None | + *BOARD | + *LUFA board hardware drivers to use (see \ref Page_DeviceSupport). | *
| LUFA_SRC_USB | - *List of LUFA USB driver source files. | - *|
| LUFA_SRC_USBCLASS | - *List of LUFA USB Class driver source files. | - *|
| LUFA_SRC_TEMPERATURE | - *List of LUFA temperature sensor driver source files. | - *|
| LUFA_SRC_SERIAL | - *List of LUFA Serial U(S)ART driver source files. | - *|
| LUFA_SRC_TWI | - *List of LUFA TWI driver source files. | - *|
| LUFA_SRC_PLATFORM | - *List of LUFA architecture specific platform management source files. | + *None | *
| Error "Makefile {X} option must be Y or N" shown when compiling. | *The specified Makefile value was configured in your project's makefile or on the command line, but was set to a value other than a Y (for "Yes") or "N" (for "No"). - * This configuration option is required to be one of the aformentioned boolean values, and other values are invalid. Set this option to either Y or N and try again. | + * This configuration option is required to be one of the aforementioned boolean values, and other values are invalid. Set this option to either Y or N and try again. *|
| Error "Unknown input source file formats: {X}" shown when compiling. | @@ -916,7 +230,7 @@ *Error "Cannot build with OBJDIR parameter set - one or more object file name is not unique" shown when compiling. | *When a project is built with a non-empty OBJDIR object directory name set, all input source files must have unique names, excluding extension and path. * This means that input files that are named identically and differ only by their path or extension are invalid when this mode is used. | - *
| Error "Source file does not exist: {X}" shown when compiling. | *The nominated input source file, specified in the user project's SRC parameter, could not be found. Ensure the source file exists and the absolute or @@ -935,17 +249,6 @@ * upgrade to the latest AVR-GCC. If the option is a valid linker option, use the prefix "-Wl," to ensure it is passed to the linker correctly. | *|
| Error "avr-gcc: error: unrecognized option '{X}'" shown when compiling. | - *An unrecognised option was supplied to the compiler, usually in the C_FLAGS, CPP_FLAGS, ASM_FLAGS or CC_FLAGS configuration - * options. The nominated compiler switch may be invalid, or unsupported by the version of AVR-GCC on the host system. Remove the unrecognised flag if invalid, or - * upgrade to the latest AVR-GCC. If the option is a valid linker option, use the prefix "-Wl," to ensure it is passed to the linker correctly. | - *|
| Error "makefile:{X}: {Y}.mk: No such file or directory" shown when make is invoked. | - *The path to the nominated makefile module was incorrect. This usually indicates that the makefile LUFA_PATH option is not set to a valid relative or - * absolute path to the LUFA library core. | - *|
| Error "makefile:{X}: {Y}.mk: No such file or directory" shown when make is invoked. | *The path to the nominated makefile module was incorrect. This usually indicates that the makefile LUFA_PATH option is not set to a valid relative or * absolute path to the LUFA library core. | @@ -964,20 +267,15 @@ *|
| Error "unknown MCU '{X}' specified" shown when compiling. | - *The specified micocontroller device model name set in the user application's makefile as the MCU parameter is incorrect, or unsupported by the + * | The specified microcontroller device model name set in the user application's makefile as the MCU parameter is incorrect, or unsupported by the * version of the compiler being used. Make sure the model name is correct, or upgrade to the latest Atmel Toolchain to obtain newer device support. | *
| Error "error: invalid suffix "x" on integer constant" shown when compiling a bootloader. | - *This is usually caused by the bc.exe application not being found in the system's PATH variable. Make sure you have the bc.exe tool - * installed correctly (see \ref Sec_Prerequisites). | - *|
| Error "undefined reference to `{X}'" shown when compiling. | *This is usually caused by a missing source file in the user application's SRC configuration parameter. If the indicated symbol is one from the LUFA - * library, you may be missing a LUFA source makefile module (see \ref Page_BuildModule_SOURCES). | + * library, you may be missing a LUFA source makefile module (see \ref Page_BuildModule_LUFA_SOURCES). *