|
|
|
@@ -0,0 +1,221 @@ |
|
|
|
A *Hello, world!* Application |
|
|
|
############################# |
|
|
|
|
|
|
|
Creating a *hello world* application is very simple. |
|
|
|
|
|
|
|
|
|
|
|
Creating a *Package Root* |
|
|
|
************************* |
|
|
|
|
|
|
|
To start, create a new directory for your project. This will be known as the |
|
|
|
*package root*, and the entirety of our project will be placed in this |
|
|
|
directory the name and location of this directory is not important, but the |
|
|
|
contents therein will be significant. |
|
|
|
|
|
|
|
.. note:: |
|
|
|
The term *package root* is further described in the :doc:`/guide/packages` page. |
|
|
|
|
|
|
|
From here on, this created directory will simply be noted as ``<root>``. In |
|
|
|
the examples, this will refer to the directory package root directory we have |
|
|
|
created. |
|
|
|
|
|
|
|
|
|
|
|
Creating the First *Source Root* |
|
|
|
******************************** |
|
|
|
|
|
|
|
Within the package root, we create our first *source root*. Since we are |
|
|
|
intending to compile files, we need to use the name that ``dds`` has designated |
|
|
|
to be the source root that may contain compilable source files: ``src/``: |
|
|
|
|
|
|
|
.. code-block:: bash |
|
|
|
|
|
|
|
mkdir src |
|
|
|
|
|
|
|
You should now have a single item in the package root, at ``<root>/src/``. This |
|
|
|
is the directory from which ``dds`` will search for source files. |
|
|
|
|
|
|
|
|
|
|
|
Creating an Application Entrypoint |
|
|
|
********************************** |
|
|
|
|
|
|
|
To add a source file to our project, we simply create a file within a source |
|
|
|
root with the appropriate file extension. Our source root is ``<root>/src/``, |
|
|
|
so we'll place a source file in there. In addition, because we want to create |
|
|
|
an *application* we need to designate that the source file provides an |
|
|
|
application *entry point*, i.e. a ``main()`` function. To do this, we simply |
|
|
|
prepend ``.main`` to the file extension. Create a file:: |
|
|
|
|
|
|
|
> <root>/src/hello-world.main.cpp |
|
|
|
|
|
|
|
and open it in your editor of choice. We'll add the classic C++ *hello, world* |
|
|
|
program: |
|
|
|
|
|
|
|
.. code-block:: c++ |
|
|
|
:linenos: |
|
|
|
:caption: ``<root>/src/hello-world.main.cpp`` |
|
|
|
|
|
|
|
#include <iostream> |
|
|
|
|
|
|
|
int main() { |
|
|
|
std::cout << "Hello, world!\n"; |
|
|
|
} |
|
|
|
|
|
|
|
|
|
|
|
Building *Hello, World* |
|
|
|
*********************** |
|
|
|
|
|
|
|
Now comes the fun part. It is time to actually compile the application! |
|
|
|
|
|
|
|
.. important:: |
|
|
|
If you intend to compile with Visual C++, the build must be executed |
|
|
|
from within a Visual Studio or Visual C++ development command prompt. These |
|
|
|
program shortcuts should be made available with any standard installation |
|
|
|
of the Visual C++ toolchain. |
|
|
|
|
|
|
|
``dds`` **will not** automatically load the Visual C++ environment. |
|
|
|
|
|
|
|
To build the program, we must provide ``dds`` with information about our |
|
|
|
program toolchain. ``dds`` comes with a few "built in" toolchain options that |
|
|
|
can be used out-of-the-box, and they'll be suitable for our purposes. |
|
|
|
|
|
|
|
- If you are compiling with GCC, the toolchain name is ``:gcc`` |
|
|
|
- If you are compiling with Clang, the toolchain name is ``:clang`` |
|
|
|
- If you are compiling with Visual C++, the toolchain name is ``:msvc`` |
|
|
|
|
|
|
|
.. note:: |
|
|
|
The leading colon ``:`` is important: This tells ``dds`` to use its |
|
|
|
built-in toolchain information rather than looking for a toolchain file of |
|
|
|
that name. |
|
|
|
|
|
|
|
To execute the build, run the ``dds build`` command as in the following |
|
|
|
example, providing the appropriate toolchain name in place of ``<toolchain>``:: |
|
|
|
|
|
|
|
> dds build -t <toolchain> |
|
|
|
|
|
|
|
For example, if you are using ``gcc``, you would run the command as:: |
|
|
|
|
|
|
|
> dds build -t :gcc |
|
|
|
|
|
|
|
If all successful, ``dds`` will emit information about the compile and link |
|
|
|
process, and then exit without error. |
|
|
|
|
|
|
|
By default, build results will be placed in a subdirectory of the package root |
|
|
|
named ``_build``. Within this directory, you will find the generated executable |
|
|
|
named ``hello-world`` (with a ``.exe`` suffix if on Windows). |
|
|
|
|
|
|
|
We should not be able to run this executable and see our ``Hello, world!``:: |
|
|
|
|
|
|
|
> ./_build/hello-world |
|
|
|
Hello, world! |
|
|
|
|
|
|
|
Obviously this isn't *all* there is to do with ``dds``. Read on to the next |
|
|
|
pages to learn more. |
|
|
|
|
|
|
|
.. note:: |
|
|
|
You're reading a very early version of these docs. There will be a lot more |
|
|
|
here in the future. Watch this space for changes! |
|
|
|
|
|
|
|
|
|
|
|
More Sources |
|
|
|
************ |
|
|
|
|
|
|
|
Modularizing our program is good, right? Let's do that. |
|
|
|
|
|
|
|
|
|
|
|
Add a Header |
|
|
|
************ |
|
|
|
|
|
|
|
Create a new subdirectory of ``src``, and we'll call it ``hello``:: |
|
|
|
|
|
|
|
> mkdir src/hello |
|
|
|
|
|
|
|
Within this directory, create a ``strings.hpp``. Edit the content in your |
|
|
|
editor of choice: |
|
|
|
|
|
|
|
.. code-block:: c++ |
|
|
|
:caption: ``<root>/src/hello/strings.hpp`` |
|
|
|
:linenos: |
|
|
|
|
|
|
|
#ifndef HELLO_STRINGS_HPP_INCLUDED |
|
|
|
#define HELLO_STRINGS_HPP_INCLUDED |
|
|
|
|
|
|
|
#include <string> |
|
|
|
|
|
|
|
namespace hello { |
|
|
|
|
|
|
|
std::string get_greeting(); |
|
|
|
|
|
|
|
} |
|
|
|
|
|
|
|
#endif |
|
|
|
|
|
|
|
|
|
|
|
Change our ``main()`` |
|
|
|
********************* |
|
|
|
|
|
|
|
Modify the content of ``<root>/src/hello-world.main.cpp`` to include our new |
|
|
|
header and to use our ``get_greeting()`` function: |
|
|
|
|
|
|
|
.. code-block:: c++ |
|
|
|
:caption: ``<root>/src/hello-world.main.cpp`` |
|
|
|
:linenos: |
|
|
|
:emphasize-lines: 1, 6 |
|
|
|
|
|
|
|
#include <hello/strings.hpp> |
|
|
|
|
|
|
|
#include <iostream> |
|
|
|
|
|
|
|
int main() { |
|
|
|
std::cout << hello::get_greeting() << '\n'; |
|
|
|
} |
|
|
|
|
|
|
|
|
|
|
|
Compiling Again, and Linking...? |
|
|
|
******************************** |
|
|
|
|
|
|
|
If you run the ``dds build`` command again, you will now see an error: |
|
|
|
|
|
|
|
.. code-block:: text |
|
|
|
|
|
|
|
[12:55:25] [info ] [dds-hello] Link: hello-world |
|
|
|
[12:55:25] [info ] [dds-hello] Link: hello-world - 57ms |
|
|
|
[12:55:25] [error] Failed to link executable '<root>/_build/hello-world'. |
|
|
|
... |
|
|
|
<additional lines follow> |
|
|
|
|
|
|
|
The problem, of course, is that we've declared ``get_greeting`` to *exist*, but |
|
|
|
be haven't *defined it*. |
|
|
|
|
|
|
|
|
|
|
|
Adding Another Compiled Source |
|
|
|
****************************** |
|
|
|
|
|
|
|
We'll add another compilable source file to our project. In the same |
|
|
|
directory as ``strings.hpp``, add ``strings.cpp``: |
|
|
|
|
|
|
|
.. code-block:: c++ |
|
|
|
:caption: ``<root>/src/hello/strings.cpp`` |
|
|
|
:linenos: |
|
|
|
|
|
|
|
#include <hello/strings.hpp> |
|
|
|
|
|
|
|
std::string hello::get_greeting() { |
|
|
|
return "Hello, world!"; |
|
|
|
} |
|
|
|
|
|
|
|
|
|
|
|
Compiling and Linking! |
|
|
|
********************** |
|
|
|
|
|
|
|
Run the ``dds build`` command again, and you'll find that the application |
|
|
|
successfully compiles and links! |
|
|
|
|
|
|
|
If you've used other build systems, you may have noticed a missing step: We |
|
|
|
never told ``dds`` about our new source file. Actually, we never told ``dds`` |
|
|
|
about *any* of our source files. We never even told it the name of the |
|
|
|
executable to generate. What gives? |
|
|
|
|
|
|
|
It turns out, we *did* tell ``dds`` all of this information by simply placing |
|
|
|
the files on the filesystem with the appropriate file paths. The name of the |
|
|
|
executable, ``hello-world``, was inferred by stripping the trailing ``.main`` |
|
|
|
from the stem of the filename which defined the entry point. |
vector-of-bool
пре 5 година