doc/src/projects/creator-projects-libraries.qdoc

   1 /****************************************************************************
   2 **
   3 ** This file is part of Qt Creator
   4 **
   5 ** Copyright (c) 2011 Nokia Corporation and/or its subsidiary(-ies).
   6 **
   7 ** Contact: Nokia Corporation (info@qt.nokia.com)
   8 **
   9 **
  10 ** GNU Free Documentation License
  11 **
  12 ** Alternatively, this file may be used under the terms of the GNU Free
  13 ** Documentation License version 1.3 as published by the Free Software
  14 ** Foundation and appearing in the file included in the packaging of this
  15 ** file.
  16 **
  17 ** If you have questions regarding the use of this file, please contact
  18 ** Nokia at info@qt.nokia.com.
  19 **
  20 ****************************************************************************/
  21
  22 // **********************************************************************
  23 // NOTE: the sections are not ordered by their logical order to avoid
  24 // reshuffling the file each time the index order changes (i.e., often).
  25 // Run the fixnavi.pl script to adjust the links to the index order.
  26 // **********************************************************************
  27
  28 /*!
  29     \contentspage index.html
  30     \previouspage creator-project-opening.html
  31     \page creator-project-qmake-libraries.html
  32     \nextpage creator-developing-meego.html
  33
  34     \title Adding Libraries to Projects
  35
  36     In addition to Qt libraries, you can add other libraries to your projects.
  37     The way the library is added depends on whether it is a system library or
  38     your own library or a 3rd party library located in the build tree of the
  39     current project or in another build tree.
  40
  41     \image qtcreator-add-library-wizard.png "Add Library wizard"
  42
  43     Because system libraries do not typically change and are often found by
  44     default, you do not need to specify the path to the library or to its
  45     includes when you add it.
  46
  47     For your own libraries and 3rd party libraries, you need to specify
  48     the paths. \QC tries to guess the include path for an external library,
  49     but you need to check it and modify it if necessary. \QC automatically
  50     adds the include path for an internal library.
  51
  52     For all libraries, select the target platforms for the application, library,
  53     or plugin.
  54
  55     Specify whether the library is statically or dynamically linked. For a
  56     statically linked internal library, \QC adds dependencies
  57     (PRE_TARGETDEPS) in the project file.
  58
  59     Depending on the development platform, some options might be detected
  60     automatically. For example, on Mac OS, the library type (\gui Library or
  61     \gui Framework) is detected automatically and the option is hidden. However,
  62     if you develop on another platform than Mac OS and want to build your
  63     project for the Mac OS, you must specify the library type.
  64
  65     The default convention on Windows is that the debug and release versions
  66     of a library have the same name, but are placed in different subdirectories,
  67     usually called \e debug and \e release. If the library path does not contain
  68     either of these folders, you cannot select the option to place the libraries
  69     in separate folders.
  70
  71     Alternatively, the letter \e d can be added to the library name for the
  72     debug version. For example, if the release version is called example.lib,
  73     the debug version is called exampled.lib. You can specify that the letter
  74     is added for the debug version and removed for the release version.
  75     If the library name ends in \e d, deselect the \gui {Remove "d" suffix
  76     for release version} option.
  77
  78     \QC supports code completion and syntax highlighting for the added
  79     libraries once your project successfully builds and links to them.
  80
  81     \section1 To Add Libraries
  82
  83     \list 1
  84
  85         \o  In the \gui Projects pane, open the project file (.pro).
  86
  87         \o  Right-click in the code editor to open the context menu and select
  88             \gui {Add Library}.
  89
  90         \o  Follow the instructions of the wizard.
  91
  92     \endlist
  93
  94     For more information about the project file settings, see
  95     \l{http://doc.qt.nokia.com/4.7/qmake-project-files.html#declaring-other-libraries}
  96     {Declaring Other Libraries}.
  97
  98     \section1 Example of Adding Internal Libraries
  99
 100     The following example describes how to add a statically linked internal
 101     library to your project.
 102
 103     \list 1
 104
 105         \o  Choose \gui {File > New File or Project > Other Projects >
 106             C++ Library} to create the library.
 107
 108             The \gui {Introduction and Product Location} dialog opens.
 109
 110             \image qtcreator-add-library-wizard-ex-1.png "Introduction and Product Location dialog"
 111
 112         \o  In the \gui Type field, select \gui {Statically Linked Library}.
 113
 114         \o  In the \gui Name field, give a name for the library. For example,
 115             \bold mylib.
 116
 117         \o  Follow the instructions of the wizard until you get to the
 118             \gui {Project Management} dialog. In the \gui {Add to project}
 119             list, select a project. For example, \bold myapp.
 120
 121         \o  In the \gui Projects pane, open the project file (.pro).
 122             For example, \bold myapp.pro.
 123
 124         \o  Right-click in the code editor to open the context menu and select
 125             \gui {Add Library > Internal Library > Next}.
 126
 127         \o  In the \gui Library field, select \bold mylib and click \gui Next.
 128
 129         \o  Click \gui Finish to add the following library declaration to the
 130             project file:
 131
 132             \code
 133             win32:CONFIG(release, debug|release): LIBS += -L$$OUT_PWD/../../../projects/mylib/release/ -lmylib
 134             else:win32:CONFIG(debug, debug|release): LIBS += -L$$OUT_PWD/../../../projects/mylib/debug/ -lmylib
 135             else:symbian: LIBS += -lmylib
 136             else:unix: LIBS += -L$$OUT_PWD/../../../projects/mylib/ -lmylib
 137
 138             INCLUDEPATH += $$PWD/../../../projects/mylib
 139             DEPENDPATH += $$PWD/../../../projects/mylib
 140
 141             win32:CONFIG(release, debug|release): PRE_TARGETDEPS += $$OUT_PWD/../../../projects/mylib/release/mylib.lib
 142             else:win32:CONFIG(debug, debug|release): PRE_TARGETDEPS += $$OUT_PWD/../../../projects/mylib/debug/mylib.lib
 143             else:unix:!symbian: PRE_TARGETDEPS += $$OUT_PWD/../../../projects/mylib/libmylib.a
 144             \endcode
 145
 146     \endlist
 147
 148 */