Tutorial: Your First Buck2 Application
Welcome! This tutorial will help you learn the basics of building your first Rust application with Buck2. We will start from the very beginning, guiding you step-by-step to get a "Hello, World!" message displayed in your terminal. Through this practical exercise, you'll acquire foundational skills for working with Buck2.
What We'll Do:
- Set up a simple project directory.
- Write a "Hello, World!" program in Rust.
- Create a BUCK file to tell Buck2 how to build our program.
- Build the Rust program using Buck2.
- Run our compiled program using Buck2.
- Briefly inspect the build targets we created.
Preqrequisites:
- Follow the previous section to set up
- Setup rust
- For this tutorial, we will use Rust. You don't need to know how to write Rust. We will only use a few basic of Rust.
Step 1: Create a New Project
First, we need to create a new buck2 project directory and set up a folder to put all our files in.
- Create a new buck2 project directory and create a new directory named
buck2_lab
inside it.
buck2 init hello_world
mkdir hello_world/buck2_lab
cd hello_world/buck2_lab
- Inside
buck2_lab
, create another directory namedgreeter_bin
, this is where all files of our Buck2 binary package will be stored.
mkdir greeter_bin
- Create
greeter_bin/src
directory, this is where all source files of our binary will live.
mkdir greeter_bin/src
Our project structure should look like this:
buck2_lab
└── greeter_bin
└── src
Step 2: Writing the "Hello, World!" Program
Now, let's write our simple Rust program.
- Inside the src directory, create a new file named main.rs.
- Open src/main.rs in your favorite text editor and add the following code:
fn main() {
println!("Hello world!");
}
This is the main function of our program. It prints "Hello world!" to the console. But we are not done yet, we need to tell Buck2 how to build our program.
Step 3: Defining the Build Target in a BUCK File
Next, we need to tell Buck2 about our program and how to build it. We do this
using a BUCK
file.
-
In the root of your
greeter_bin
directory (not inside src), create a new file namedBUCK
. -
Add the following content to this BUCK file:
rust_binary(
name = "main",
srcs = ["src/main.rs"],
)
Let's briefly see what this does (we'll keep explanations minimal, just enough for this step! ):
load(...)
is a load statement. It tells Buck2 to load the definition of therust_binary
.rust_binary
is a Buck2 rule that tells Buck2 how to build a Rust binary.name = "main"
: We're giving our build target a name, "main". This is how we'll refer to it in Buck2 commands.srcs = ["src/main.rs"]
: This tells Buck2 that the source code for this "main" target is oursrc/main.rs
file.
Our project structure should look like this:
buck2_lab
└── greeter_bin
├── BUCK
└── src
└── main.rs
Step 4: Building the Application with Buck2
With our Rust code and BUCK file in place, let's build the application!
- Open your terminal and make sure you are in the
greeter_bin
directory. - Run the following command:
buck2 build :main --show-output
buck2 build :main
tells Buck2 to build the target named main. The:main
part means the target is defined in the BUCK file in the root of this package (greeter_bin
).--show-output
tells Buck2 to show the path of our built binary.
- Expected Output: You should see output similar to this
...
BUILD SUCCEEDED
root//buck2_lab/greeter_bin:main /.../buck2_lab/buck-out/v2/gen/root/200212f73efcd57d/buck2_lab/greeter_bin/__main__/main
BUILD SUCCEEDED
indicates that Buck2 successfully build our target.root//buck2_lab/greeter_bin:main
is the full target label name of our target.- Think of the
:main
we used in the step 2 as a relative path to the target from within its package (greeter_bin
). - The full name
root//buck2_lab/greeter_bin:main
is like an absolute path, uniquely identifying the target within your entire project (fbsource). buck-out/.../__main__/main
is the path of our binary output. It is the path relative path to fbsource. You can use--show-full-output
instead of--show-output
to get the absulate path.
Step 5: Running Your Application with Buck2
Since our target is a runnable target, we can run it by buck2 run
- In your terminal (still in the
greeter_bin
directory), execute:
buck2 run :main
This command tells Buck2 to run the main
target. Buck2 will build it if it
hasn't been built already, and then execute it. (i.e. We can do this whithout
step 4)
- Expected Output: You will see:
Hello world!
There it is! Our program ran successfully and printed the message.
Step 6: Inspecting Your Target (Optional)
This step is optional, but it's good to know how you can ask Buck2 about the targets you've defined.
- To see the target that we defined (still in the
greeter_bin
directory), run:
buck2 targets :
or
buck2 targets fbcode//scripts/nero/buck2_lab/greeter_bin:
- Expected Output:
This will show all the targets we defined,
root//buck2_lab/greeter_bin:main
Conclusion
Congratulations! 🎉
You have successfully created, built, and run your first application using Buck2! We've walked through
- Setting up the project structure.
- Writing a simple Rust program.
- Defining a rust_binary target in a BUCK file.
- Using
buck2 build
to compile the code. - Using
buck2 run
to execute the program. - Using
buck2 targets
to inspect the target.
You've taken your first concrete steps into the world of Buck2.