Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Make generator documentation #955

Merged
merged 7 commits into from Dec 3, 2018
Merged
@@ -23,6 +23,7 @@ packages can be consumed, created, and continuously deployed/tested with each, a
integrations/b2
integrations/qmake
integrations/premake
integrations/make
integrations/qbs
integrations/meson
integrations/docker
@@ -0,0 +1,135 @@
.. _make:

Make
====

Conan provides integration with plain Makefiles by means of the ``make`` generator. If you are using ``Makefile`` to build your project you
could get the information of the dependencies in a *conanbuildinfo.mak* file. All you have to do is indicate the generator like this:

.. code-block:: text
:caption: *conanfile.txt*

[generators]
make

.. code-block:: text
:caption: *conanfile.py*

class MyConan(ConanFile):
...
generators = "make"

Example
-------

We are going to use the same example from :ref:`getting_started`, a MD5 Encrypter app.

This is the main file for it:

.. code-block:: cpp
:caption: main.cpp

#include "Poco/MD5Engine.h"
#include "Poco/DigestStream.h"

#include <iostream>


int main(int argc, char** argv)
{
Poco::MD5Engine md5;
Poco::DigestOutputStream ds(md5);
ds << "abcdefghijklmnopqrstuvwxyz";
ds.close();
std::cout << Poco::DigestEngine::digestToHex(md5.digest()) << std::endl;
return 0;
}

As this project relies on the Poco Libraries we are going to create a *conanfile.txt* with our requirement and declare there the Make
generator too:

.. code-block:: text
:caption: conanfile.txt

[requires]
Poco/1.9.0@pocoproject/stable

[generators]
make

In order to use this generator within your project, use the following Makefile as a reference:

.. code-block:: makefile
:caption: Makefile

include conanbuildinfo.mak

#----------------------------------------
# Make variables for a sample App
#----------------------------------------

CXX_SRCS = \
main.cpp

CXX_OBJ_FILES = \
main.o

EXE_FILENAME = \
main


#----------------------------------------
# Prepare flags from variables
#----------------------------------------

CPPFLAGS += $(addprefix -I, $(CONAN_INCLUDE_PATHS))
CPPFLAGS += $(addprefix -D, $(CONAN_DEFINES))
LDFLAGS += $(addprefix -L, $(CONAN_LIB_PATHS))
LIBS += $(addprefix -l, $(CONAN_LIBS))


#----------------------------------------
# Make Commands
#----------------------------------------

COMPILE_CXX_COMMAND ?= \
g++ -c $(CXXFLAGS) $(CPPFLAGS) $< -o $@
This conversation was marked as resolved by danimtb

This comment has been minimized.

Copy link
@solvingj

solvingj Nov 29, 2018

Contributor

$(CXXFLAGS) should just be $(CFLAGS) since there is actually no variable called $(CXXFLAGS) in this example, nor is one propagated by Conan. Conan only propagates a single variable called CFLAGS. Technically, it doesn't matter here because there were no CFLAGS defined in this example, so both will result in an empty string, but we should definitely make the example correct.


CREATE_EXE_COMMAND ?= \
g++ $(CXX_OBJ_FILES) \
$(LDFLAGS) $(LIBS) \
-o $(EXE_FILENAME)


#----------------------------------------
# Make Rules
#----------------------------------------

.PHONY : exe
exe : $(EXE_FILENAME)

$(EXE_FILENAME) : $(CXX_OBJ_FILES)
$(CREATE_EXE_COMMAND)

%.o : $(CXX_SRCS)
$(COMPILE_CXX_COMMAND)

Now we are going to let Conan retrieve the dependencies and generate the dependency information in a *conanbuildinfo.mak*:

.. code-block:: bash
$ conan install .
Then let's call :command:`make` to generate our project:

- Use this command for Windows Visual Studio:

.. code-block:: bash
$ make exe
Now you can run your application with ``./main``.

.. seealso::

Check the complete reference of the :ref:`Make generator<make_generator>`.
@@ -36,3 +36,4 @@ Available generators:
generators/text
generators/json
generators/premake
generators/make
@@ -0,0 +1,82 @@
.. _make_generator:

make
====

.. container:: out_reference_box

This is the reference page for ``make`` generator.
Go to :ref:`Integrations/make<make>` if you want to learn how to integrate your project or recipes with make.

This generators creates a file named *conanbuildinfo.mak* with information of dependencies in different variables that can be used for your
make builds.

Variables
---------

Variables per package. ``<PKG-NAME>`` placeholder is filled with the name of the Conan package.

+--------------------------------------+----------------------------------------------------------------------+
| NAME | VALUE |
+======================================+======================================================================+
| CONAN_ROOT_<PKG-NAME> | Absolute path to root package folder |
+--------------------------------------+----------------------------------------------------------------------+
| CONAN_SYSROOT_<PKG-NAME> | System root folder |
+--------------------------------------+----------------------------------------------------------------------+
| CONAN_INC_PATHS_<PKG-NAME> | Headers folders |
This conversation was marked as resolved by danimtb

This comment has been minimized.

Copy link
@solvingj

solvingj Nov 29, 2018

Contributor

I've seen references to CONAN_INC_PATHS and CONAN_INCLUDE_PATHS. Not sure what the final choice was, but need to make sure references are consistent everywhere.

+--------------------------------------+----------------------------------------------------------------------+
| CONAN_LIB_PATHS_<PKG-NAME> | Library folders |
+--------------------------------------+----------------------------------------------------------------------+
| CONAN_BIN_PATHS_<PKG-NAME> | Binary folders |
+--------------------------------------+----------------------------------------------------------------------+
| CONAN_BUILD_PATHS_<PKG-NAME> | Build folders |
+--------------------------------------+----------------------------------------------------------------------+
| CONAN_RES_PATHS_<PKG-NAME> | Resources folders |
+--------------------------------------+----------------------------------------------------------------------+
| CONAN_LIBS_<PKG-NAME> | Binary folders |
This conversation was marked as resolved by danimtb

This comment has been minimized.

Copy link
@solvingj

solvingj Nov 29, 2018

Contributor

Delete this entry, it looks like a copy/paste error.

+--------------------------------------+----------------------------------------------------------------------+
| CONAN_LIBS_<PKG-NAME> | Library names to link with |
+--------------------------------------+----------------------------------------------------------------------+
| CONAN_DEFINES_<PKG-NAME> | Library definitions |
+--------------------------------------+----------------------------------------------------------------------+
| CONAN_CFLAGS_<PKG-NAME> | Library C flags |
This conversation was marked as resolved by danimtb

This comment has been minimized.

Copy link
@solvingj

solvingj Nov 29, 2018

Contributor

Change "C flags" to "C Compiler flags" for clarity.

+--------------------------------------+----------------------------------------------------------------------+
| CONAN_CPPFLAGS_<PKG-NAME> | Library CXX flags |
This conversation was marked as resolved by danimtb

This comment has been minimized.

Copy link
@solvingj

solvingj Nov 29, 2018

Contributor

The variable name CPPFLAGS is misleading. CPPFLAGS is actually short for "C Pre-Processor Flags", nothing to do with C++. In GNU Make, there is a separate implicit variable called CXXFLAGS that we don't do anything with in Conan... that would be specifically for the C++ compiler.

+--------------------------------------+----------------------------------------------------------------------+
| CONAN_SHAREDLINKFLAGS_<PKG-NAME> | Library Shared linker flags |
+--------------------------------------+----------------------------------------------------------------------+
| CONAN_EXELINK_FLAGS_<PKG-NAME> | Executable linker flags |
+--------------------------------------+----------------------------------------------------------------------+

Conan also declares some **global variables** with the aggregated values of all our requirements. The values are ordered in the right order
according to the dependency tree.

+--------------------------------+----------------------------------------------------------------------+
| NAME | VALUE |
+================================+======================================================================+
| CONAN_ROOTPATH | Aggregated root folders |
+--------------------------------+----------------------------------------------------------------------+
| CONAN_SYSROOT | Aggregated system root folders |
+--------------------------------+----------------------------------------------------------------------+
| CONAN_INC_PATHS | Aggregated header folders |
+--------------------------------+----------------------------------------------------------------------+
| CONAN_LIB_PATHS | Aggregated library folders |
+--------------------------------+----------------------------------------------------------------------+
| CONAN_BIN_PATHS | Aggregated binary folders |
+--------------------------------+----------------------------------------------------------------------+
| CONAN_BUILD_PATHS | Aggregated build folders |
+--------------------------------+----------------------------------------------------------------------+
| CONAN_RES_PATHS | Aggregated resource folders |
+--------------------------------+----------------------------------------------------------------------+
| CONAN_LIBS | Aggregated library names to link with |
+--------------------------------+----------------------------------------------------------------------+
| CONAN_DEFINES | Aggregated library definitions |
+--------------------------------+----------------------------------------------------------------------+
| CONAN_CFLAGS | Aggregated C flags |
This conversation was marked as resolved by danimtb

This comment has been minimized.

Copy link
@solvingj

solvingj Nov 29, 2018

Contributor

Change "C flags" to "C Compiler flags" for clarity.

+--------------------------------+----------------------------------------------------------------------+
| CONAN_CPPFLAGS | Aggregated CXX flags |
This conversation was marked as resolved by danimtb

This comment has been minimized.

Copy link
@solvingj

solvingj Nov 29, 2018

Contributor

"CXX flags" should say "C Preprocessor flags"

+--------------------------------+----------------------------------------------------------------------+
| CONAN_SHAREDLINKFLAGS | Aggregated Shared linker flags |
+--------------------------------+----------------------------------------------------------------------+
| CONAN_EXELINKFLAGS | Aggregated Executable linker flags |
+--------------------------------+----------------------------------------------------------------------+
ProTip! Use n and p to navigate between commits in a pull request.
You can’t perform that action at this time.