🔗 CAmalgamator

A powerful C amalgamator CLI tool that combines multiple C files into a single file ✨

Perfect for creating single-header libraries, distributing projects, and simplifying builds!

🎯 What is CAmalgamator? (Super Simple Explanation!)

Imagine you have a LEGO castle made of many pieces scattered around your room. 🏰

CAmalgamator is like a magic tool that:

Finds all your LEGO pieces (C files) 📦
Connects them together 🔗
Gives you one complete castle (single C file) ✨

📚 In Programming Terms:

If you have a C project with files like:

main.c (your main program)
helper.c (some useful functions)
math.c (math functions)
helper.h and math.h (header files)

CAmalgamator combines ALL of these into ONE single file! 🎉

🤔 Why is this AMAZING for beginners?

✅ SUPER EASY to Share

Before: "Hey, here are 20 files you need to compile my program..."
After: "Hey, here's 1 file - just compile and run!" 🚀

✅ NO Complex Build Systems

Before: Need Makefiles, CMake, or other scary build tools 😰
After: Just gcc single_file.c -o my_program ✨

✅ Perfect for Learning

See exactly what code is included
No mysterious "where does this function come from?" moments
Easy to understand the entire program flow

✅ Great for Competitions

Programming contests often want single files
Easy to submit to online judges
No dependency headaches

📥 Download & Installation (Choose Your Adventure!)

🚨 Total Beginner? Start with the "🎮 Super Easy Download" section below!

🎮 Super Easy Download (No Compilation Needed!)

Just want to use it RIGHT NOW? Download the ready-to-run version for your computer:

🖥️ Your Computer	� Download This	🏃‍♂️ How to Use
� Linux	CAmalgamator.out	Download → Make executable → Run!
🪟 Windows (64-bit)	CAmalgamator64.exe	Download → Double-click → Use!
🪟 Windows (32-bit)	CAmalgamatori32.exe	Download → Double-click → Use!

🚀 Super Quick Installation (Copy & Paste!)

🐧 Linux Users (Easiest Way Ever!):

# Just copy and paste this into your terminal!
curl -L https://github.com/OUIsolutions/CAmalgamator/releases/download/0.0.4/CAmalgamator.out -o CAmalgamator
chmod +x CAmalgamator

# Now you can use it like this:
./CAmalgamator --help

🐧 Ubuntu/Debian Users (Even Easier!):

# Download the package
wget https://github.com/OUIsolutions/CAmalgamator/releases/download/0.0.4/CAmalgamator.deb

# Install it (you'll need to enter your password)
sudo dpkg -i CAmalgamator.deb

# Now it's installed system-wide! Use it anywhere:
CAmalgamator --help

🧑‍💻 Advanced Downloads (For Developers)

📁 File	🎯 Best For	📝 Description
�️ CAmalgamator.c	Developers who want to compile	Complete source code
� CAmalgamatorApiOne.h	Use in your C programs	Full API library
� CAmalgamatorApiNoDependenciesIncluded.h	Minimal integration	Lightweight version
📦 CAmalgamator.rpm	Fedora/RHEL/CentOS	RPM package

🏃‍♂️ Quick Start Guide (For Total Beginners!)

Don't panic! This is easier than making instant noodles! 🍜

🎬 Step 1: Your First Amalgamation (The Basics)

Let's start with the simplest possible example:

# This is THE most basic command you'll ever need!
./CAmalgamator --file main.c --output combined.c

🤔 What just happened?

--file main.c → "Hey CAmalgamator, start with this file!"
--output combined.c → "Put the final result in this file!"

That's it! CAmalgamator will:

🔍 Look at main.c
🕵️‍♂️ Find all the #include statements
🔗 Follow each include and grab that code
📝 Put everything together in combined.c

🎬 Step 2: Real-World Example (Let's Do This Together!)

Imagine you have these files:

my_awesome_project/
├── main.c              ← Your main program
├── calculator.h        ← Calculator functions
├── calculator.c        ← Calculator implementation  
├── helpers.h           ← Helper functions
└── helpers.c           ← Helper implementation

🧑‍💻 What's in each file:

main.c:

#include <stdio.h>
#include "calculator.h"
#include "helpers.h"

int main() {
    printf("Hello from my awesome program!\n");
    int result = add(5, 3);
    print_result(result);
    return 0;
}

calculator.h:

#ifndef CALCULATOR_H
#define CALCULATOR_H
int add(int a, int b);
int subtract(int a, int b);
#endif

calculator.c:

#include "calculator.h"
int add(int a, int b) { return a + b; }
int subtract(int a, int b) { return a - b; }

helpers.h:

#ifndef HELPERS_H  
#define HELPERS_H
void print_result(int result);
#endif

helpers.c:

#include <stdio.h>
#include "helpers.h"
void print_result(int result) {
    printf("The result is: %d\n", result);
}

🚀 Now, let's combine everything:

./CAmalgamator --file main.c --output single_awesome_program.c

🎉 BOOM! Now you have ONE file called single_awesome_program.c with EVERYTHING inside!

You can compile and run it with just:

gcc single_awesome_program.c -o my_program
./my_program

No more worrying about:

❌ "Did I include all the files?"
❌ "Why can't the compiler find my functions?"
❌ "How do I link all these files together?"

🎬 Step 3: Test It Yourself!

Create a simple test:

Create test_main.c:

#include <stdio.h>
#include "test_math.h"

int main() {
    printf("Testing CAmalgamator!\n");
    printf("2 + 3 = %d\n", simple_add(2, 3));
    return 0;
}

Create test_math.h:

#ifndef TEST_MATH_H
#define TEST_MATH_H
int simple_add(int a, int b);
#endif

Create test_math.c:

#include "test_math.h"
int simple_add(int a, int b) {
    return a + b;
}

Run CAmalgamator:

./CAmalgamator --file test_main.c --output combined_test.c

Compile and run:

gcc combined_test.c -o test_program
./test_program

Expected output:

Testing CAmalgamator!
2 + 3 = 5

� Congratulations! You just used CAmalgamator successfully!

⚙️ Command-Line Options (All the Cool Features!)

🎯 Beginner Tip: Start with just --file and --output. Learn the other options later!

🔥 Essential Options (You NEED These!)

🏷️ Flag	📝 What It Does	🚨 Required?	💡 Example
`--file` or `--f`	The starting file (where to begin)	✅ YES	`--file main.c`
`--output` or `--o`	Where to save the result	✅ YES	`--output combined.c`

🛡️ Safety Options (Protect Yourself!)

🏷️ Flag	📝 What It Does	🔧 Default	💡 When to Use
`--maxbyte`	Max size in bytes	100MB	When you want to limit file size exactly
`--maxmega`	Max size in megabytes	100MB	Easier! `--maxmega 50` for 50MB limit
`--maxreq`	Max recursion depth	1000	If includes go too deep

🎛️ Advanced Control Options (For Power Users!)

🏷️ Flag	📝 What It Does	🎯 Perfect For	💡 Example
`--nochange` or `--nc`	Don't replace these includes	Keep system includes as-is	`--nochange stdio.h`
`--noinclude` or `--ni`	Skip these files completely	Exclude external libraries	`--noinclude dependencies/`
`--perpetual` or `--p`	Allow multiple inclusions	Headers that can be included many times	`--perpetual common_macros.h`

🌟 Real-World Examples:

🥇 Beginner Example:

# Just combine everything - simple!
./CAmalgamator --file src/main.c --output build/single_file.c

🥈 Intermediate Example:

# Limit size and exclude system headers
./CAmalgamator --file main.c --output combined.c --maxmega 10 --nochange stdio.h

🥉 Advanced Example:

# Skip dependencies folder but allow perpetual includes
./CAmalgamator --file src/main.c --output release/final.c \
  --noinclude dependencies/ \
  --perpetual common_macros.h \
  --maxmega 50

🚨 Common Beginner Mistakes (And How to Avoid Them!)

❌ DON'T DO THIS:

# Missing required flags - this will fail!
./CAmalgamator main.c

✅ DO THIS INSTEAD:

# Always include both --file and --output
./CAmalgamator --file main.c --output combined.c

❌ DON'T DO THIS:

# Using same name for input and output - BAD!
./CAmalgamator --file main.c --output main.c

✅ DO THIS INSTEAD:

# Use different names to avoid overwriting
./CAmalgamator --file main.c --output main_combined.c

🧑‍💻 API Usage (For Programmers Who Want to Integrate!)

🎯 Beginner Note: This section is for people who want to use CAmalgamator inside their own C programs. If you just want to use the command-line tool, you can skip this section!

🚀 Quick Setup (Get the API Library)

Download the API header file:

# Get the complete API (easiest way)
curl -L https://github.com/OUIsolutions/CAmalgamator/releases/download/0.002/CAmalgamatorApiOne.h -o CAmalgamatorApiOne.h

🎬 Simple Example (Your First API Program!)

Create a file called my_amalgamator.c:

#include <stdio.h>
#include "CAmalgamatorApiOne.h"

int main() {
    // Initialize the amalgamator
    CAmalgamatorNamesapce amalgamator = newCAmalgamatorNamesapce();
    
    // Settings (you can change these!)
    const char *starting_file = "src/cli/main.c";  // Where to start
    int max_recursion = 1000;                      // How deep to go
    int max_size = amalgamator.ONE_MB * 10;        // Max 10MB output
    
    // Do the magic! ✨
    CAmalgamatorErrorOrContent *result = amalgamator.generate_amalgamation_simple(
        starting_file,
        max_size,
        max_recursion
    );
    
    // Check if it worked
    if(result->error) {
        printf("❌ Oops! Something went wrong: %s\n", result->error_msg);
        amalgamator.free_error_or_string(result);
        return 1;
    }
    
    // Success! Print the combined code
    printf("✅ Success! Here's your combined code:\n\n%s", result->content);
    
    // Clean up memory (important!)
    amalgamator.free_error_or_string(result);
    
    printf("\n🎉 All done!\n");
    return 0;
}

Compile and run:

gcc my_amalgamator.c -o my_amalgamator
./my_amalgamator

🎛️ Advanced Example (With Custom Control!)

Want more control over what gets included? Here's how:

#include <stdio.h>
#include "CAmalgamatorApiOne.h"

CAmalgamatorNamesapce amalgamator;

// This function decides what to do with each file
short my_custom_callback(const char *filename, const char *include_name, void *args) {
    printf("🔍 Found: %s (included from %s)\n", include_name, filename);
    
    // You can add your own logic here!
    
    // For example, skip all .txt files:
    if (strstr(include_name, ".txt") != NULL) {
        printf("⏭️  Skipping .txt file: %s\n", include_name);
        return amalgamator.DONT_INCLUDE;
    }
    
    // Include everything else once
    return amalgamator.INCLUDE_ONCE;
}

int main() {
    amalgamator = newCAmalgamatorNamesapce();
    
    const char *starting_file = "src/cli/main.c";
    int max_recursion = 1000;
    int max_size = amalgamator.ONE_MB * 10;
    void *custom_args = NULL;  // You can pass custom data here
    
    // Use the custom callback for more control
    CAmalgamatorErrorOrContent *result = amalgamator.generate_amalgamation(
        starting_file,
        max_size,
        max_recursion,
        my_custom_callback,  // Our custom function!
        custom_args
    );
    
    if(result->error) {
        printf("❌ Error: %s\n", result->error_msg);
        amalgamator.free_error_or_string(result);
        return 1;
    }
    
    printf("✅ Success! Here's your custom amalgamation:\n\n%s", result->content);
    amalgamator.free_error_or_string(result);
    return 0;
}

🎯 Callback Return Values (What Each One Does)

When you use a custom callback, you can return different values to control behavior:

🏷️ Namespace	🏷️ Pure Constant	📝 What It Does	💡 When to Use
`amalgamator.DONT_INCLUDE`	`CAMALGAMATOR_DONT_INCLUDE`	Skip this file completely	External libraries you don't want
`amalgamator.DONT_CHANGE`	`CAMALGAMATOR_DONT_CHANGE`	Keep the `#include` as-is	System headers like `<stdio.h>`
`amalgamator.INCLUDE_ONCE`	`CAMALGAMATOR_INCLUDE_ONCE`	Include the file once	Most normal files
`amalgamator.INCLUDE_PERPETUAL`	`CAMALGAMATOR_INCLUDE_PERPETUAL`	Include every time it's found	Macros that can be included multiple times

🚨 Important Notes for Beginners:

Always check for errors! The API can fail if files don't exist or are too big.
Don't forget to free memory! Always call free_error_or_string() when done.
Start simple! Use generate_amalgamation_simple() first, then try the advanced version.

🔨 Building from Scratch (For Advanced Users!)

🎯 Beginner Note: You don't need this section if you just downloaded the ready-made executables above! This is only for people who want to compile CAmalgamator themselves.

📋 Prerequisites (What You Need First)

You'll need these tools installed:

🦄 Darwin Build System (Version 0.020+)
🐳 Docker OR 🫖 Podman (for containerized builds)
🐧 Linux Environment (recommended)

🚀 One-Line Darwin Installation (Linux Only!)

# Install Darwin build system in one command
curl -L https://github.com/OUIsolutions/Darwin/releases/download/0.7.0/darwin.out -o darwin.out && sudo chmod +x darwin.out && sudo mv darwin.out /usr/bin/darwin

📁 Clone and Build

# 1. Clone the repository
git clone https://github.com/OUIsolutions/CAmalgamator.git
cd CAmalgamator

# 2. Build all variants (this will take a while!)
darwin run_blueprint build/ --mode folder amalgamation_build alpine_static_build windowsi32_build windowsi64_build rpm_static_build debian_static_build

🎉 After building, you'll have:

Linux executables
Windows executables (32-bit and 64-bit)
RPM packages
DEB packages
Static builds
And more!

🤔 What Gets Built?

🏗️ Build Target	📝 Description	🎯 Output
`amalgamation_build`	Single C file version	`CAmalgamator.c`
`alpine_static_build`	Static Linux binary	Linux executable
`windowsi32_build`	32-bit Windows	`.exe` file
`windowsi64_build`	64-bit Windows	`.exe` file
`rpm_static_build`	RPM package	`.rpm` file
`debian_static_build`	Debian package	`.deb` file

🚨 Troubleshooting Common Build Issues

❌ "darwin: command not found"

Solution: Make sure Darwin is installed and in your PATH

❌ "Docker/Podman not found"

Solution: Install Docker or Podman for containerized builds

❌ "Permission denied"

Solution: Make sure you have execute permissions on build scripts

🆘 Need Help? (We've Got You Covered!)

🤝 Community Support

🐛 Found a Bug? Create an Issue
💡 Have a Feature Idea? Suggest It Here
⭐ Like the Project? Give us a star on GitHub!

📚 Common Questions

Q: "Can I use this with C++?" A: CAmalgamator is designed for C, but it might work with simple C++ code. Try it and see!

Q: "What about very large projects?" A: Use the --maxmega flag to set size limits. For huge projects, consider breaking them into smaller parts first.

Q: "Can I exclude certain system headers?" A: Yes! Use --nochange to keep system includes like <stdio.h> as-is.

Q: "Is it safe to use in production?" A: Absolutely! Many developers use amalgamation for distribution. Just test thoroughly first.

🎉 Success Stories & Use Cases

🌟 Perfect For:

🎓 Students: Submit single-file assignments easily
🏆 Competitive Programming: Many contests prefer single files
📦 Library Distribution: Create easy-to-use single-header libraries
🚀 Embedded Systems: Simplify builds for microcontrollers
📱 Mobile Development: Reduce complexity in mobile C libraries

💬 What Users Say:

"CAmalgamator saved me hours of build configuration headaches!" - DevStudent2024

"Perfect for my competitive programming setup. One command and I'm ready to submit!" - CodeWarrior

"Made distributing my C library so much easier. My users love the single-header approach!" - LibraryMaker

🌟 Ready to Simplify Your C Development?

⬇️ Download Now | ⭐ Star on GitHub | 🐛 Report Issues

Made with ❤️ by OUIsolutions

Simplifying C development, one amalgamation at a time! ✨

Name		Name	Last commit message	Last commit date
Latest commit History 90 Commits
build		build
src		src
.gitignore		.gitignore
DEPENDENCIES.md		DEPENDENCIES.md
LICENSE		LICENSE
README.md		README.md

License

OUIsolutions/CAmalgamator

Folders and files

Latest commit

History

Repository files navigation