ians-wiki - Tumblr blog

ians-wiki · 3 years ago

Text

Doxygen Primer

By Ian Elsbree, 2022-09-19

Table of Contents

Doxygen Primer

Table of Contents

Introduction

Doxygen

Doxygen Comments

Doxyfiles

Using Someone Else's Doxyfile

Turning LaTeX into PDF

Conclusion

Introduction

Welcome to the Doxygen Primer! This document is meant to get you up to speed on Doxygen, a documentation generator that makes it easy to document your code. This primer is not an in-depth usage guide, nor a complete documentation, nor an exhaustive list of features. It is only a basic introduction to the usage of Doxygen, primarily written for use in the CS-120, CS-170, and CS-180 courses. Of course, this document will apply to other uses, but its scope is limited intentionally. With that said, let's see what all the fuss is about.

Doxygen

Doxygen is a program. It runs when you run the command doxygen. It expects something called a doxyfile (explained later) to be in the current working directory, named Doxyfile.

Here is the official Doxygen Manual.

Doxygen's purpose is to scan source code files, in this context .c or .cpp (or .h) files, and generate documentation on the code within them, so that other programmers can more easily understand the purpose of your code and how to use it. It does this by generating files in either HTML format or LaTeX format (or both), which you can then use either as an HTML webpage, or use another tool such as pdf-latex to generate a PDF file from the LaTeX files. Either of these options will result in a document which explains how your code works to the reader.

Doxygen is not complicated to use in a simple use case. Most basically, you only have to run the command doxygen -g to generate a default configuration file, and then run the command doxygen to create the documentation for your code. However, there is some more information which will be useful to know about.

Doxygen Comments

Doxygen scans the comments in your source code. To make Doxygen aware of the information it needs to generate the documentation, you need to use special comments. You will need to put a Doxygen comment at the top of your file (a file header), specifying information about the file, as well as comments above each of your functions (function headers), specifying information about each of them. Here is an example Doxygen-style comment (this one is for a function):

/** * @brief Dynamically allocates a new node, initializing it with data. * * @param value The value to store in the node * @param label The label to associate with the node * @return A pointer to the newly made node */

Okay, what do we see here? A few things:

Doxygen comments begin with an extra * symbol, so you get /** instead of the normal /*.

The asterisks at the beginning of each line are optional. They just look nice.

Each line contains what's called a tag, followed by information.

Tags start with either a @ or a \ (either one works).

Tags denote some kind of information that would be useful to have in the documentation of your code.

The name of the tag determines how it is used in the documentation.

The information after the tag is displayed in the documentation.

Doxygen comments end like normal comments.

The most notable tags you will use are:

@file - Used as the name of the file the code is in.

@author - Used to credit the author of the file.

@date - Used to record the date of authorship of the file, or, in the case of the CS courses I mentioned earlier, the due date of the assignment.

@par - Used to display any information that does not have its own tag. If you use this tag and place a field name, and the field value on the following line, it will be displayed in the same way the author and date tags are.

@brief - Used to give a short description to a file or a function.

@param - Used to give the parameters of a function. The first word after the tag is the name of the parameter, and everything after that is the description of the parameter.

@return - Used to give the return value of a function.

There are other tags, although they are not as frequent, depending on the type of programming you do. Refer to the official manual for more information.

Doxyfiles

When you run Doxygen, it looks for a configuration file called a doxyfile. The default name it will look for is Doxyfile, with no file extension. A doxyfile is a text file, much in the same way that a C source code file is a text file. If you look at the default doxyfile (generated with the command doxygen -g), you can see the structure of a doxyfile, with options, followed by =, followed by values.

Notable options include:

PROJECT_NAME - The title of your documentation. Be sure to change this.

GENERATE_LATEX and GENERATE_HTML - Select what kind of documentation files to generate.

There are many, many more options available, although these are the most critical. Again, refer to the official manual for more information.

Using Someone Else's Doxyfile

If someone such as your professor provides a file named Doxyfile, good news! You don't have to configure one yourself. However, this is very important: make sure you edit the doxyfile to change the PROJECT_NAME to something suitable.

Other than that, using someone else's doxyfile is as simple as putting it the directory of your project and running the command doxygen. That's it. You should see a new folder or two, depending on what type of documentation you're generating. Inside these folders is your fresh, hot-off-the-press documentation. Have fun!

Turning LaTeX into PDF

You may have generated LaTeX documentation, but to view that, you'll need a program that can render LaTeX markup. Instead, you can generate a PDF document that more people's computers will be able to display easily.

Inside of the latex folder that was generated, you'll see a makefile, intended for the program make. Surprise! I have a primer on make and makefiles here. But for this usage, you should only need to run the commands cd latex to get into the latex directory and make to generate a PDF of your documentation. You will need a command called pdflatex for the makefile to work properly, which can be gotten as part of a package set called texlive.

After you run make, you'll see a file called refman.pdf is generated. That file is a PDF document that contains the full documentation for your project. Congratulations! Doesn't it look pretty?

Conclusion

You should now have some introductory knowledge of how to use Doxygen effectively. If you feel there is anything this document did not cover that you think it should, or anything you're left wondering after reading, or anything I can improve, please let me know! My goal is for this document to be easily read and comprehended, and to give you all the knowledge you need to be a more effective developer.

#guide #doxygen

2 notes · View notes

ians-wiki · 3 years ago

Text

Makefile Primer

Table of Contents

Makefile Primer

Table of Contents

Introduction

Make

Makefiles

Structure

Variables

Targets

Commands

Using Someone Else's Makefile

Writing Your Own Makefile

Conclusion

Introduction

This primer will get you up to speed on what the program make and makefiles are, and what they are used for. It will not be an in-depth usage guide, nor a complete documentation, nor an exhaustive list of features. It is only a basic introduction to their usage, primarily written for use in the CS-120 and CS-170 courses. This document will apply to other uses, but its scope is limited intentionally. With that said, let's get see what all the fuss is about.

Make

make is a program. It runs when you run the command make. It expects something called a makefile (explained later) to be in the current working directory, named Makefile.

In the use case I'm addressing, which is compiling, running, and testing relatively simple C and C++ programs (only a few source files at the most), here's what make does when you run it with a makefile: it runs other commands. That's it. It runs commands that you could just run yourself. The benefit of using make, however, is that it can run complex commands, while you only have to type make. It can also run different sets of commands, and modify those commands, by simply passing the name of a "target" (also explained later) as a command argument. Doing that looks like this: make [targetName] (e.g. make compile or make test1).

Makefiles

Makefiles are text files. They contain variables, targets, and commands, stored as text. They are where make gets its behavior from. The makefile is what tells make what to do when you run it, and it's also where you write the commands you want make to execute for each target.

Structure

Makefiles are divided into sections. There is the top of the file, where global variables are declared, and there are targets below that. A target is a name or set of names (separated by spaces) followed by a colon (:). In more advanced applications, there are prerequisites listed after the colon, but for our uses you can ignore that feature. On the lines following the target name(s), the commands to run for that target are listed. Each command you want to have executed must be indented with a tab character (not spaces). A following line which is not indented and has a colon after a name, will be recognized as the next target.

An example makefile, to give you an idea of the structure:

VARIABLE=some text that I'd like to replace the name of this variable COMPILECOMMAND=gcc COMPILEARGUMENTS=-O -Wextra -Werror -Wall -ansi -pedantic EXECUTABLENAME=prg.exe compile: $(COMPILECOMMAND) -o $(EXECUTABLENAME) sourcefile.c $(COMPILEARGUMENTS) 1 2: ./$(EXECUTABLENAME) $@ memtest: valgrind ./$(EXECUTABLENAME) 1

Okay, that has little bit more than I've covered so far, but it will all be explained.

Variables

Variables in a makefile are used to store long pieces of text that you want to have in multiple different places. In the way we use them here, they're a bit like using #define in C/C++. Variable declarations look like this: VARIABLENAME=variable value and should each be on their own line. Using a variable is done by writing $(VARIABLENAME) somewhere else. For example, in a command. This means that $(VARIABLENAME) in the command will be replaced by variable value. As you can see in the example above, some uses for variables include compiler argument lists and executable names.

Targets

Targets are the names you put after make to tell make what you want it to do. If you don't specify a target name when running make, it will default to the first target in the makefile. As mentioned earlier, targets are of the form targetName:. When you tell make to use a target, it will execute all commands on the lines following that target, until it gets to the next target in the file. Targets are followed by a list of commands, with each line indented with a tab character.

If you want a target to run with slight variation, but pretty much the same behavior as another, you may find it useful to have multiple names for the same target. This is most obvious in the case of having multiple different tests to run, where each test is specified by passing a different value to your executable. If you want this, place each target name on the same line, separated by spaces, and a colon at the end (like a normal target). Now you can use the name of the target in your command with $@. This will be replaced with whichever name you call. In the example above, the target 1 2: can be run with either make 1 or make 2. If I call make 2, then $@ in the command below the target name will be replaced with 2, making the command ./prg.exe 2.

Commands

Here's where make actually does things. Commands are executed just like they would be if you ran them yourself on the command line. They are executed in order, from top to bottom. They don't do much special, except that any variables will be resolved to their values before the command actually runs.

Using Someone Else's Makefile

Say, for example, someone else on your team alreay wrote a makefile for your project. Or say, for example, your professor included a makefile with your assignment. Using their makefile is simple.

Look at the contents of the makefile and determine what the available targets are. Again, these are lines that have one or more names followed by a colon. Each name should be descriptive, but you can always check to see what commands are listed under each target. Then, you can run the command make [target] to execute a specific target, or just make to execute whatever the first target in the file is. If you want/need to edit someone else's makefile, you should know how to write your own makefile first.

Writing Your Own Makefile

Say, for example, no one gave you a makefile. Making your own makefile is simple.

Are there commands you have to run every time you compile your project? Are there commands you have to run every time you run and test your program? Group each of these into a target. If you have multiple tests that are run with command-line arguments passed to your program, you can make use of the multiple-name feature of target names. Make your target names descriptive of their purpose, but short. Remember, the point of make is to require less typing in the future.

Are there parts of commands that are shared between multiple different commands (such as executable names, flag lists, etc.)? Put those into variables so they can be easily modified later.

Constructing a makefile is easiest if you first identify the commands required to build and test your project.

Conclusion

You should now have some introductory knowledge of how to write and use make and makefiles effectively. If you feel there is anything this document did not cover that you think it should, or anything you're left wondering after reading, or anything I can improve, please let me know! My goal is for this document to be easily read and comprehended, and to give you all the knowledge you need to be a more effective developer.

#guide #makefile

1 note · View note