Making an Executable

Not infrequently, some poor lisp newb will ask how to make an executable in lisp. The answer of course, is "what do you mean by 'executable?'" If the newb is lucky, somebody will eventually take break from pretending not to know exactly what he means and point him to save-lisp-and-die. But, they will hasten to add, making an executable is really a silly thing to do, so why bother?

Fresh from the mind of Sergey Kolos, Cusp contributor extraordinaire and the man who recently brought us integrated unit testing comes this wild innovation: a menu item called "Create Exe." That's right. In the next version, all Cusp users will have to do is right-click on their project and select "Create Exe." That, my friends, is what user-friendliness looks like.

So buck up, newbs. With luck, the endless discussions on what the meaning of the word "is" is will soon be replaced by the simple advice to "use Cusp."

I wouldn't hold my breath, though.

Making a small Common Lisp Project (in Cusp)

In honor of my recent addition to Planet Lisp, and as a special thank you to Xach, I figured I'd counter-blog his old post on how to make a lisp project (in Slime). You can go read that if you want. Here's the Cusp way:

Make the project. Go to New > Lisp Project. Enter the name of your project. You're done.

Write the code. You'll notice that a file named "main.lisp" has been opened for you. Put your lisp code there. You can compile the definitions as you write them (with Alt+C), but that's mostly a vestigial holdover from Slime. Cusp is smart. Save your file and it will automatically compile any new or changed top-level forms. (It'll even undefine functions that you've deleted.)

Later on... If you close Cusp, when you come back you'll need to reload the project. To do this, right-click on the .asd file in the project, and choose "Load Project." You may also need to change the package in the REPL to match the one for this project.

So what is all this stuff?

You've got all you need to start hacking, but you probably want to know what's going on behind the scenes. The New Project wizard creates a project folder with three files in it: main.lisp, defpackage.lisp, and [project name].asd. Here's what they do:

main.lisp is the main code file. Put the guts of your program here. You can, of course, create additional files as your project grows. More on that in a moment.

defpackage.lisp defines the package for this lisp project, which is basically the lisp equivalent of a namespace. You could pollute cl-user with your project internals, but that's just asking for trouble down the line. You'll note that main.lisp started out with (in-package :[project-name]). You'll want to make sure any new files you add start that way, too.

If you want to import symbols from another package into your project (so you can say split rather than cl-ppcre:split) put the name of that package into the :use section. This is similar to using in C++ or C#, or import in Java. If your project turns into a library to be used by other projects, you would put any exported symbols into the :export section. Notice that by default, you are already importing :cl.

[project-name].asd is best thought of as your project file. This tells Lisp what libraries to load up for your project, and what files are part of your project. You'll notice that defpackage and main are already listed in the :components section. If you add more files to your project, make sure to tack them on to the end of that list. Files will be loaded in the order they are listed.

Dependencies are also handled by the asd file. If, as in the earlier example, you want to use cl-ppcre, make sure to add it to the :depends-on section.

Asd files can get more complicated if you need, but this should be enough to take care of you in 95% of all cases. Happy hacking!

Smoothing the way

Periodically, I like to ego-surf to find out what people think of Cusp. It's usually complimentary, which is always nice to see (even if they tend to call it "CUSP"), but I like to keep a special eye out for people who are having issues, since that usually points me toward ways I can improve the experience for people.

Recently, I ran into this post. The author had a load statement in his file that just wasn't working. Why? Because he was calling it merely "file.lisp." No absolute path was given, and since sbcl is almost certainly not being run in the same directory as that file, it's not going to be able to find it without more information.

The sad part for me is that I'm not entirely sure there's much I can do for this kind of problem. Firstly, a person could very easily have multiple projects going at the same time, so determining the proper working directory is a chancy thing. Even then, automatically shifting working directories is the kind of anti-feature that soon causes more trouble than it saves.

This isn't an issue isolated to this one guy, though. Judging from the comments and recent posting on the Cusp discussion boards, others have tried to do the same thing. I think the real answer here is actually to educate people on the usage of asd files, and to get them to treat them as project files. I intend to add some comments to the auto-generated asd files to get people on the right track, but that's probably the best I can do.

Sadly, I couldn't resolve that issue technologically, but I was able to do something about one of the comments on that entry. The problem? When you create a new project, Cusp automatically wraps it all into a new package. Once you know what you're doing, this a very nice thing, because it is what you should be doing anyway. But when you're completely fresh to Lisp, you're not likely to realize that the stuff in the file is going to one package, while the Repl is sitting in another.

The fix was easy. Now when you make a new project, the REPL is automatically switched to that project's package. 99% of the time, this is what you'll want to do, and it should allow newbies to experiment without first having to learn all about the packaging system.