Better "hello, world" tutorial

docs/conf.py

@@ -23,5 +23,9 @@ pygments_style = None
 # -- Options for HTML output -------------------------------------------------
 html_theme = 'pyramid'
 html_theme_options = {}
-html_static_path = []
+html_static_path = ['_static']
 html_sidebars = {}
+
+
+def setup(app):
+    app.add_stylesheet('tweaks.css')

docs/guide/getting-started.rst

@@ -1,26 +0,0 @@
-Getting Started
-###############
-
-Using ``dds`` is extremely simple:
-
-#. Create a new directory. This will be our *package root*.
-#. Create a subdirectory named ``src/``.
-#. Create a file named ``application.main.cpp``.
-#. Add a ``main()`` function to our new source file.
-#. Depending on your compiler:
-    #. If you are using GCC, run the ``dds build -t :gcc`` command from the
-       package root.
-    #. If you are using Clang, run the ``dds build -t :clang`` command from the
-       package root.
-    #. If you are using Visual C++, run the :code:`dds build -t :msvc` command
-       from the package root from a developer command prompt.
-
-You will now have a ``_build`` directory, and it will contain a newly compiled
-``application``!
-
-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!

docs/guide/index.rst

@@ -6,7 +6,6 @@ User Guide
 .. toctree::
     :maxdepth: 2
 
-    getting-started
     packages
     toolchains
     source-dists

docs/index.rst

@@ -9,11 +9,12 @@ learn, but I'm glad you're here! I hope you find ``dds`` useful to you and your
 projects.
 
 If you're completely new and have no idea what the project is about, check out
-the :doc:`guide/getting-started` page.
+the :doc:`tut/index` page.
 
 .. toctree::
     :maxdepth: 2
 
+    tut/index
     guide/index
     design
 

docs/tut/hello-world.rst

@@ -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.

docs/tut/index.rst

@@ -0,0 +1,18 @@
+Tutorials and Beginner's Guide
+##############################
+
+The child pages here contain introductory material for getting started with
+using ``dds``. If you don't know where to start, this will be a good
+place to begin!
+
+.. note::
+   The shell samples in these pages are written with Unix-flavored commands,
+   but the analogous process will work just as well on Windows systems.
+   Translate as appropriate.
+
+
+.. toctree::
+    :maxdepth: 2
+
+    hello-world
+